Add poc-rest-owl-loop plugin: AI-powered project scaffolding workflow

[nsheaps]

Summary

• Add poc-rest-owl-loop plugin (renamed from rest-owl) — a 7-phase workflow for turning simple project ideas into fully researched, specified, designed, and validated software projects
• Include 22 research notes analyzing the concept landscape (spec-driven development, agentic engineering, visual regression testing)
• Structure follows all repo conventions (external hooks.json, camelCase settings, proper directory layout, shared lib symlinks)

Review Feedback Addressed

• Switched hook script from raw echo to hook-logging.sh structured output with hook_run/hook_respond
• Added hook-logging.sh symlink to plugin lib/
• Made command file config-aware for artifacts directory path (no longer hardcodes docs/rest-owl/)

Plugin Phases

0. Intake — Clarify the idea
1. Competitive Research — Analyze 5-10 existing products
2. Feature Specification — Detailed specs with acceptance criteria
3. Visual Design — Design system, wireframes, HTML mockups
4. Architecture — Tech decisions + project constitution (CLAUDE.md)
5. Implementation Planning — Ordered milestones
6. Build & Validate — Test-first implementation with visual regression CI
7. Handoff — Architecture walkthrough and maintenance guide

Test plan

• Validate plugin structure passes mise run validate
• Lint passes mise run lint
• CI check-version-files, lint, validate all green
• Plugin installs correctly via marketplace
• /poc-rest-owl-loop command works end-to-end

https://claude.ai/code/session_0191H4s9PX5VxKfmKnrq3aYF

[github-actions]

Plugin Version Status

Versions are auto-bumped in PRs. Manual bumps to higher versions are preserved.

Plugin	Base	Current	Action
poc-rest-owl-loop	0.0.0	0.1.0	Already bumped

[henry-nsheaps]

❌ Missing log.sh symlink will crash the SessionStart hook — one fix needed before merge

❌ log.sh symlink missing from lib/ — hook-logging.sh depends on it and will crash at runtime (see inline comment, also prior thread)
✅ All 3 issues from earlier reviews addressed (Task tool removed, $(find...) template fixed, raw echo → hook-logging.sh)
✅ Plugin structure follows all repo conventions (external hooks.json, camelCase settings, shared lib symlinks)
✅ 22 research docs with real sources and critical analysis
✅ Well-organized 7-phase workflow with clear artifact-driven checkpoints
✅ Detection hook reads artifactsDir from config with proper 3-tier resolution

🖱️ Click to expand for full details

Blocking Issue: Missing log.sh Symlink

hook-logging.sh resolves its directory via BASH_SOURCE[0] and sources log.sh from the same path (lines 43-44 of shared/lib/hook-logging.sh):

_HOOK_LOGGING_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "${_HOOK_LOGGING_DIR}/log.sh"

The plugin's lib/ directory only contains two symlinks (hook-logging.sh and plugin-config-read.sh). When the SessionStart hook runs, this source call will fail and crash the hook.

Per shared-libs.md: "When hook-logging.sh is symlinked, log.sh must also be symlinked (it's a dependency)." Verified all 48+ other plugins with hook-logging.sh also include log.sh.

Fix: ln -s ../../../shared/lib/log.sh plugins/poc-rest-owl-loop/lib/log.sh

Previous Review Issues — All Resolved

All three issues from prior reviews have been addressed:

1. Task tool removed (review #1) — SKILL.md allowed-tools now lists only valid tools. Fixed in 6cfe741.
2. $(find ...) CI template fixed (review #1) — validation-pipeline/SKILL.md now uses the correct two-step pattern with $GITHUB_OUTPUT + ${{ steps.diffs.outputs.files }}. Fixed in 6cfe741.
3. Hook uses hook-logging.sh (review #2) — Detection script uses hook_run/hook_respond with hook_log instead of raw echo. Fixed in 0a1c033.
4. Command file config-aware (review #2) — Documents configurable artifactsDir path.

Plugin Structure

Follows all repository conventions:

• plugin.json with required fields (name poc-rest-owl-loop, version 0.1.0, description, author) per plugin-development.md
• External hooks/hooks.json per plugin-hooks-organization.md
• Settings keys in camelCase per settings-key-naming.md
• Shared lib symlinks for hook-logging.sh and plugin-config-read.sh (just missing log.sh)
• marketplace.json entry added by CD workflow, not manually edited

Hook Script

detect-poc-rest-owl-loop-project.sh is well-structured:

• set -euo pipefail
• Reads artifactsDir from config via plugin_get_config
• Exits silently when no artifacts exist (correct per hook-output-patterns.md)
• Uses hook_run/hook_respond lifecycle (correct per shared-libs.md)
• Clean phase detection checking expected artifact files
• 5-second timeout in hooks.json appropriate for lightweight file checks

Skills & Command

All 5 skills declare appropriate allowed-tools for their phases. The orchestrator skill correctly coordinates phases with human approval gates. The command file provides a clean entry point with pre-flight detection that checks multiple possible artifact directories.

Research Documentation

22 research notes covering spec-driven development, agentic engineering, visual regression testing. Spot-checked multiple docs — well-sourced with real URLs, publication dates, balanced analysis, and actionable insights tied back to plugin design decisions.

Settings

poc-rest-owl-loop.settings.yaml is well-structured with 9 configurable keys, all camelCase. README configuration table matches the settings file. Defaults are sensible for the POC scope.

Score Rationale

Quality 85%: All prior issues fixed. The missing log.sh symlink is a runtime crash bug that prevents this score from being higher. Once fixed, this would be 92%+.

Security N/A: No security-sensitive code — documentation, bash file-existence checks, and skill/command definitions only.

Simplicity 78%: 2,954 lines across 36 files is a large PR. The complexity maps to the ambitious 7-phase orchestration scope with 5 skills + 22 research docs. Each skill is well-separated with clear boundaries.

Confidence 93%: Sixth review pass with full file analysis. The log.sh dependency is confirmed by reading hook-logging.sh source (lines 43-44), cross-referencing all 48+ other plugins' lib/ directories via git ls-tree, and the explicit requirement in shared-libs.md. Verified via git ls-tree -r that lib/ contains exactly 2 files (no log.sh).

Recommended follow-ups (non-blocking):

• Consider noting tool choices (Tailwind, Bun, Playwright) as defaults/suggestions rather than requirements, so the workflow adapts to user preferences stated in Phase 0
• Add skills for Phase 4 (Architecture) and Phase 5 (Planning) if the plugin scope grows beyond POC
• Consider adding hook-output.sh symlink if additional hooks are added in future versions

[henry-nsheaps]

❌ Still missing: log.sh symlink — this will crash the SessionStart hook at runtime.

This was flagged in the previous review thread and has not been addressed in subsequent commits.

hook-logging.sh sources log.sh from its own resolved directory (source lines 43-44):

_HOOK_LOGGING_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "${_HOOK_LOGGING_DIR}/log.sh"

The lib/ directory currently only has two symlinks:

• hook-logging.sh → ../../../shared/lib/hook-logging.sh
• plugin-config-read.sh → ../../../shared/lib/plugin-config-read.sh

Per shared-libs.md: "When hook-logging.sh is symlinked, log.sh must also be symlinked (it's a dependency)." Every other plugin in the repo (48+) that uses hook-logging.sh also includes log.sh.

Fix:

cd plugins/poc-rest-owl-loop/lib/
ln -s ../../../shared/lib/log.sh log.sh