maestro-flow 0.5.31 → 0.5.33

package/.agents/skills/prompt-generator/specs/agent-design-spec.md

@@ -0,0 +1,299 @@
+# Agent Design Specification
+
+Guidelines for Claude Code **agent definition files** (role + domain expertise). Agents own identity, knowledge, and quality standards — NOT orchestration flow.
+
+## Content Separation Principle
+
+Agents are spawned by commands via `delegate_subagent()`. The agent file defines WHO the agent is and WHAT it knows. It does NOT define WHEN or HOW it gets invoked.
+
+| Concern | Belongs in Agent | Belongs in Command |
+|---------|-----------------|-------------------|
+| Role identity (`<role>`) | Yes | No |
+| Domain expertise | Yes | No |
+| Output format/structure | Yes | No |
+| Quality heuristics | Yes | No |
+| Self-check criteria | Yes | No |
+| Philosophy/principles | Yes | No |
+| Discovery protocol | Yes | No |
+| Specificity examples | Yes | No |
+| Argument parsing | No | Yes |
+| User interaction | No | Yes |
+| Flow control | No | Yes |
+| Agent spawning | No | Yes |
+| Status banners | No | Yes |
+| Revision loop logic | No | Yes |
+
+## YAML Frontmatter
+
+```yaml
+---
+name: agent-name
+description: One-line purpose. Spawned by /command-name orchestrator.
+tools: Read, Write, Bash, Glob, Grep    # Tools this agent needs
+color: green                             # Optional: terminal color
+---
+```
+
+**Naming convention:** `{domain}-{role}` or `{project}-{role}` — e.g., `gsd-planner`, `gsd-plan-checker`, `code-reviewer`.
+
+## Content Structure
+
+Agent files use XML semantic tags. `<role>` is ALWAYS first after frontmatter.
+
+### Section Catalog
+
+Derived from GSD agent patterns (`gsd-planner`, `gsd-plan-checker`, `gsd-phase-researcher`):
+
+| Section | Purpose | When to Include |
+|---------|---------|-----------------|
+| `<role>` | Identity, spawner, responsibilities | **Always** |
+| `<project_context>` | How to discover project conventions | Agent reads project files |
+| `<philosophy>` | Guiding principles, anti-patterns | Agent has opinionated approach |
+| `<context_fidelity>` | Honor upstream decisions (locked/deferred/discretion) | Agent receives user decisions |
+| `<upstream_input>` | What the agent receives and how to use it | Agent has structured input |
+| `<discovery_levels>` | Research depth protocol (L0-L3) | Agent does research |
+| `<task_breakdown>` | Task anatomy, sizing, ordering | Agent produces tasks |
+| `<dependency_graph>` | How to build dependency graphs | Agent manages dependencies |
+| `<output_format>` | Exact output structure with templates | Agent produces structured output |
+| `<core_principle>` | Central verification or design principle | Agent has one key insight |
+| `<output_contract>` | Return markers to orchestrator | **Always** |
+| `<quality_gate>` | Self-check before returning | **Always** |
+
+### Section Ordering Convention
+
+```
+<role>              ← Identity (always first)
+<project_context>   ← How to orient in the project
+<philosophy>        ← Guiding beliefs
+<upstream_input>    ← What agent receives
+<context_fidelity>  ← How to honor decisions
+<core_principle>    ← Key insight
+... domain sections ← Expertise (2-6 sections)
+<output_contract>   ← Return protocol
+<quality_gate>      ← Self-check (always last content section)
+```
+
+## Section Writing Rules
+
+### `<role>` — Identity (ALWAYS FIRST)
+
+Pattern from `gsd-planner.md` and `gsd-plan-checker.md`:
+
+```markdown
+<role>
+You are a {role name}. You {primary action verb} {what you produce}.
+
+Spawned by:
+- `/{command}` orchestrator (standard mode)
+- `/{command} --flag` orchestrator (variant mode)
+- `/{command}` in revision mode (updating based on checker feedback)
+
+Your job: {One sentence — what downstream consumers get from you.}
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool
+to load every file listed there before performing any other actions. This is your
+primary context.
+
+**Core responsibilities:**
+- **FIRST: {Most important action}** ({why it's first})
+- {Responsibility 2 — verb phrase}
+- {Responsibility 3 — verb phrase}
+- {Responsibility 4 — verb phrase}
+- Return structured results to orchestrator
+</role>
+```
+
+### `<project_context>` — Project Discovery
+
+Pattern from `gsd-planner.md`:
+
+```markdown
+<project_context>
+Before {acting}, discover project context:
+
+**Project instructions:** Read `./CLAUDE.md` if it exists. Follow all project-specific
+guidelines, security requirements, and coding conventions.
+
+**Project skills:** Check `.claude/skills/` directory if exists:
+1. List available skills (subdirectories)
+2. Read `SKILL.md` for each skill
+3. Load specific files as needed during {action}
+4. Ensure {output} accounts for project patterns
+</project_context>
+```
+
+### `<philosophy>` — Guiding Principles
+
+Pattern from `gsd-planner.md`:
+
+```markdown
+<philosophy>
+## {Principle Name}
+
+{Core belief about how this agent approaches work.}
+
+| Context Usage | Quality | Agent's State |
+|---------------|---------|---------------|
+| 0-30% | PEAK | Thorough |
+| 50-70% | DEGRADING | Efficiency mode |
+| 70%+ | POOR | Rushed |
+
+**Anti-patterns (delete if seen):**
+- {Anti-pattern 1 with specific indicator}
+- {Anti-pattern 2 with specific indicator}
+</philosophy>
+```
+
+### `<upstream_input>` — Structured Input Handling
+
+Pattern from `gsd-plan-checker.md`:
+
+```markdown
+<upstream_input>
+**{Input name}** (if exists) — {Source description}
+
+| Section | How You Use It |
+|---------|----------------|
+| `## Section A` | LOCKED — {must implement exactly}. Flag if contradicted. |
+| `## Section B` | Freedom areas — {can choose approach}, don't flag. |
+| `## Section C` | Out of scope — {must NOT include}. Flag if present. |
+</upstream_input>
+```
+
+### `<context_fidelity>` — Decision Honoring
+
+Pattern from `gsd-planner.md`:
+
+```markdown
+<context_fidelity>
+## CRITICAL: User Decision Fidelity
+
+**Before creating ANY {output}, verify:**
+
+1. **Locked Decisions** — MUST be implemented exactly as specified
+   - If user said "use library X" → {output} MUST use X, not alternative
+   - If user said "card layout" → {output} MUST implement cards
+
+2. **Deferred Ideas** — MUST NOT appear in {output}
+   - If user deferred "search" → NO search tasks allowed
+
+3. **Discretion Areas** — Use your judgment
+   - Make reasonable choices and document in {output}
+
+**Self-check before returning:**
+- [ ] Every locked decision has coverage
+- [ ] No deferred idea appears
+- [ ] Discretion areas handled reasonably
+
+**If conflict exists** (research vs user decision):
+- Honor the user's locked decision
+- Note: "Using X per user decision (research suggested Y)"
+</context_fidelity>
+```
+
+### Domain Sections — One Concern Each
+
+Name sections after the domain concept. Include concrete examples in EVERY section.
+
+**Required elements per domain section:**
+
+| Element | Minimum |
+|---------|---------|
+| Good vs bad comparison table | 1 per section |
+| Decision/routing table | 1 per section (if conditional logic exists) |
+| Format template | 1 per section (if structured output) |
+| Concrete example | 2+ per section |
+
+**Example from gsd-planner.md `<task_breakdown>`:**
+
+```markdown
+<task_breakdown>
+## Task Anatomy
+
+Every task has four required fields:
+
+**<files>:** Exact paths.
+- Good: `src/app/api/auth/login/route.ts`
+- Bad: "the auth files"
+
+**<action>:** Specific instructions.
+- Good: "Create POST endpoint accepting {email, password}, validates using bcrypt,
+  returns JWT in httpOnly cookie with 15-min expiry. Use jose library."
+- Bad: "Add authentication"
+
+## Specificity Examples
+
+| TOO VAGUE | JUST RIGHT |
+|-----------|------------|
+| "Add auth" | "Add JWT auth with refresh rotation, jose library, httpOnly cookie" |
+| "Style the dashboard" | "Tailwind: 3-col grid on lg, 1 on mobile, card shadows, hover states" |
+
+**Test:** Could a different agent execute without clarifying questions?
+</task_breakdown>
+```
+
+### `<output_contract>` — Return Protocol
+
+```markdown
+<output_contract>
+## Return Protocol
+
+Return ONE of these markers as the LAST section of output:
+
+### Success
+```
+## TASK COMPLETE
+
+{Summary of what was produced}
+{Artifact locations: file paths}
+{Key metrics: counts, coverage}
+```
+
+### Blocked
+```
+## TASK BLOCKED
+
+**Blocker:** {What's missing or preventing progress}
+**Need:** {Specific action/info that would unblock}
+**Attempted:** {What was tried before declaring blocked}
+```
+
+### Checkpoint (needs user decision)
+```
+## CHECKPOINT REACHED
+
+**Question:** {Decision needed from user}
+**Context:** {Why this matters}
+**Options:**
+1. {Option A} — {effect on output}
+2. {Option B} — {effect on output}
+```
+</output_contract>
+```
+
+### `<quality_gate>` — Self-Check (ALWAYS LAST)
+
+```markdown
+<quality_gate>
+Before returning, verify:
+- [ ] {Check 1 — concrete, grep-verifiable}
+- [ ] {Check 2 — concrete, counts/exists}
+- [ ] {Check 3 — concrete, structural}
+- [ ] {Check 4 — no prohibited content}
+</quality_gate>
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Wrong | Correct Approach |
+|-------------|----------------|------------------|
+| Agent contains `ask_user` | Agents don't interact with users | Return `## CHECKPOINT REACHED` |
+| Agent parses `$ARGUMENTS` | Arguments belong to the command | Receive pre-parsed values in prompt |
+| Agent displays banners | UI is the command's job | Return structured data |
+| `<role>` is not first section | Identity must be established first | Always lead with `<role>` |
+| Generic section names | Hard to scan, unclear scope | Name after domain concept |
+| No examples in domain sections | Rules without examples are ambiguous | Include comparison tables |
+| Agent spawns other agents | Spawning belongs to commands | Request via `## CHECKPOINT REACHED` |
+| Agent defines its own invocation syntax | That's the command's responsibility | Document in `Spawned by:` only |
+| Domain section covers multiple concerns | Violates single-concern rule | Split into separate sections |

package/.agents/skills/prompt-generator/specs/command-design-spec.md

@@ -0,0 +1,367 @@
+# Command Design Specification
+
+Guidelines for Claude Code **command files** (orchestration workflows). Commands own process flow, user interaction, and agent coordination — NOT domain expertise.
+
+## Content Separation Principle
+
+| Concern | Belongs in Command | Belongs in Agent |
+|---------|-------------------|-----------------|
+| Argument parsing | Yes | No |
+| Path resolution | Yes | No |
+| User prompts (ask_user) | Yes | No |
+| Status banners | Yes | No |
+| Agent spawning (Task) | Yes | No |
+| Flow control (if/else routing) | Yes | No |
+| Init/context loading (CLI tools) | Yes | No |
+| Revision loops | Yes | No |
+| Domain knowledge | No | Yes |
+| Quality heuristics | No | Yes |
+| Output format rules | No | Yes |
+| Role identity | No | Yes |
+
+## YAML Frontmatter
+
+```yaml
+---
+name: command-name           # Required: lowercase with hyphens
+description: Description     # Required: brief purpose
+argument-hint: "[args]"      # Optional: argument format hint
+allowed-tools: Tool1, Tool2  # Optional: restricted tool set
+---
+```
+
+## Path Structure
+
+```
+.claude/commands/deploy.md           # Top-level command
+.claude/commands/issue/create.md     # Grouped command
+~/.claude/commands/global-status.md  # User-level command
+.claude/skills/my-skill/SKILL.md     # Skill file (see Skill Variant below)
+```
+
+## Content Structure
+
+Commands use XML semantic tags with process steps inside `<process>`:
+
+| Tag | Required | Purpose |
+|-----|----------|---------|
+| `<purpose>` | Yes | What + when + what it produces (2-3 sentences) |
+| `<required_reading>` | Commands only | @ file references loaded before execution |
+| `<process>` | Yes | Steps — numbered or named (see Step Styles below) |
+| `<auto_mode>` | Optional | Behavior when `--auto` flag present |
+| `<offer_next>` | Recommended | Formatted completion status + next actions |
+| `<success_criteria>` | Yes | Checkbox list of verifiable conditions |
+
+## Skill Variant
+
+Skills (`.claude/skills/*/SKILL.md`) follow command structure with critical differences due to **progressive loading** — skills are loaded inline into the conversation context, NOT via file resolution.
+
+### Key Differences: Skill vs Command
+
+| Aspect | Command | Skill |
+|--------|---------|-------|
+| Location | `.claude/commands/` | `.claude/skills/*/SKILL.md` |
+| Loading | Slash-command invocation, `@` refs resolved | Progressive inline loading into conversation |
+| `<required_reading>` | Yes — `@path` refs auto-resolved | **NO** — `@` refs do NOT work in skills |
+| External file access | `@` references | `read_file()` tool calls within `<process>` steps |
+| Phase files | N/A | `read_file("phases/01-xxx.md")` within process steps |
+| Frontmatter | `name`, `description`, `argument-hint` | `name`, `description`, `allowed-tools` |
+
+### Skill-Specific Rules
+
+1. **NO `<required_reading>` tag** — Skills cannot use `@` file references. All external context must be loaded via `read_file()` tool calls within `<process>` steps.
+
+2. **Progressive phase loading** — For multi-phase skills with phase files in `phases/` subdirectory, use inline `read_file()`:
+   ```javascript
+   // Within process step: Load phase doc on-demand
+   read_file("phases/01-session-discovery.md")
+   // Execute phase logic...
+   ```
+
+3. **Self-contained content** — All instructions, rules, and logic must be directly in the SKILL.md or loaded via `read_file()` at runtime. No implicit file dependencies.
+
+4. **Frontmatter uses `allowed-tools:`** instead of `argument-hint:`:
+   ```yaml
+   ---
+   name: my-skill
+   description: What this skill does
+   allowed-tools: Agent, Read, Write, Bash, Glob, Grep
+   ---
+   ```
+
+### Skill Content Structure
+
+| Tag | Required | Purpose |
+|-----|----------|---------|
+| `<purpose>` | Yes | What + when + what it produces (2-3 sentences) |
+| `<process>` | Yes | Steps with inline `read_file()` for external files |
+| `<auto_mode>` | Optional | Behavior when `-y`/`--yes` flag present |
+| `<success_criteria>` | Yes | Checkbox list of verifiable conditions |
+
+**Note**: `<offer_next>` is less common in skills since skills often chain to other skills via `invoke_skill()` calls.
+
+## Step Styles
+
+GSD uses two step styles. Choose based on command nature:
+
+### Style A: Numbered Steps (for complex orchestrators)
+
+Used by: `plan-phase.md`, `new-project.md`, `research-phase.md`
+
+Best for: Multi-agent orchestration, long workflows with branching, revision loops.
+
+```markdown
+<process>
+
+## 1. Initialize
+
+Load context, parse arguments.
+
+## 2. Validate Phase
+
+Check preconditions.
+
+## 3. Spawn Agent
+
+Display banner, construct prompt, spawn.
+
+## 4. Handle Result
+
+Route on return markers.
+
+## 5. Present Status
+
+Display offer_next.
+
+</process>
+```
+
+### Style B: Named `<step>` Blocks (for focused commands)
+
+Used by: `execute-phase.md`, `discuss-phase.md`, `verify-work.md`
+
+Best for: Sequential steps, clear atomic actions, step-level priority.
+
+```markdown
+<process>
+
+<step name="initialize" priority="first">
+Load context, parse arguments.
+</step>
+
+<step name="validate_phase">
+Check preconditions.
+</step>
+
+<step name="spawn_agent">
+Construct prompt, spawn agent.
+</step>
+
+<step name="report">
+Display results.
+</step>
+
+</process>
+```
+
+### Which style to use?
+
+| Criteria | Numbered | Named `<step>` |
+|----------|----------|----------------|
+| Agent spawning with revision loops | Yes | No |
+| Multiple conditional branches | Yes | No |
+| Sequential with clear boundaries | No | Yes |
+| Steps reference each other by number | Yes | No |
+| First step needs `priority="first"` | No | Yes |
+
+## Init Pattern
+
+Most GSD commands start by loading context via CLI tools:
+
+```bash
+INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init {command} "${ARG}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+For non-GSD commands, the equivalent is reading config/state files:
+
+```bash
+# Read project state
+CONFIG=$(cat .claude/config.json 2>/dev/null || echo '{}')
+```
+
+## Banner Style
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SKILL ► ACTION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Display banners before major phase transitions (agent spawning, user decisions, completion).
+
+## Agent Spawning Pattern
+
+Commands spawn agents via `delegate_subagent()` with structured prompts:
+
+```javascript
+delegate_subagent({
+  subagent_type: "agent-name",
+  prompt: filled_prompt,
+  description: "Verb Phase {X}",
+  run_in_background: false
+})
+```
+
+### Prompt Structure for Agents
+
+The prompt passed to agents uses XML blocks:
+
+```markdown
+<objective>
+What to accomplish — specific and measurable.
+</objective>
+
+<files_to_read>
+- {path1} (description — what this file provides)
+- {path2} (description)
+</files_to_read>
+
+<additional_context>
+**Phase:** {number}
+**Mode:** {standard | revision | gap_closure}
+Extra info the agent needs.
+</additional_context>
+
+<output>
+Write to: {output_path}
+</output>
+```
+
+### Return Handling
+
+Commands route on agent return markers:
+
+```markdown
+## Handle Agent Return
+
+- **`## TASK COMPLETE`:** Display confirmation, continue to next step.
+- **`## TASK BLOCKED`:** Display blocker, offer user options:
+  1) Provide context  2) Skip  3) Abort
+- **`## CHECKPOINT REACHED`:** Present question to user, relay response.
+```
+
+## Revision Loop Pattern
+
+For commands that iterate between generation and verification:
+
+```markdown
+## N. Revision Loop (Max 3 Iterations)
+
+Track `iteration_count` (starts at 1).
+
+**If iteration_count < 3:**
+- Display: "Sending back for revision... (iteration {N}/3)"
+- Spawn agent with revision prompt + checker issues
+- After agent returns → spawn checker again, increment count
+
+**If iteration_count >= 3:**
+- Display remaining issues
+- Offer: 1) Force proceed  2) Provide guidance  3) Abandon
+```
+
+## Auto Mode Pattern
+
+Commands supporting `--auto` flag define behavior in `<auto_mode>`:
+
+```markdown
+<auto_mode>
+## Auto Mode Detection
+
+Check if `--auto` flag is present in $ARGUMENTS.
+
+**If auto mode:**
+- Skip confirmation prompts
+- Use smart defaults for optional choices
+- Auto-approve intermediate results
+- Chain to next command on success
+
+**Document requirement (if applicable):**
+- What --auto requires as input
+- Error message if requirements not met
+</auto_mode>
+```
+
+## offer_next Pattern
+
+```markdown
+<offer_next>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ SKILL ► TASK COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**{Summary line}**
+
+| Key | Value |
+|-----|-------|
+| ... | ...   |
+
+Status: {metric 1} | {metric 2}
+
+───────────────────────────────────────────────────────
+
+## Next Up
+
+**{Primary next action}**
+
+/{next-command} {args}
+
+<sub>/clear first — fresh context window</sub>
+
+───────────────────────────────────────────────────────
+
+**Also available:**
+- /{alt-1} — description
+- /{alt-2} — description
+
+───────────────────────────────────────────────────────
+</offer_next>
+```
+
+## ask_user Pattern
+
+For user decisions within commands:
+
+```markdown
+ask_user(
+  header: "Context",
+  question: "Descriptive question?",
+  options: [
+    { label: "Option A", description: "Effect of choosing A" },
+    { label: "Option B", description: "Effect of choosing B" }
+  ]
+)
+
+If "Option A": {action}
+If "Option B": {action}
+```
+
+## Shell Correctness Rules
+
+| Rule | Wrong | Correct |
+|------|-------|---------|
+| Multi-line output | `echo "{ ... }"` | `cat <<'EOF' > file`...`EOF` |
+| Variable init | Use `$VAR` after conditional | Initialize BEFORE conditional |
+| Error exit | `echo "Error"` (no exit) | `echo "Error" && exit 1` |
+| Quoting | `$VAR` bare | `"$VAR"` quoted |
+| Prerequisites | Implicit tool usage | Declare in `<prerequisites>` |
+| File existence | Assume file exists | `test -f "$FILE" && ...` |
+
+## Step Naming Conventions
+
+| Domain | Typical Steps |
+|--------|--------------|
+| Multi-Agent Pipeline | Initialize, Validate, Spawn Agent A, Handle A Result, Spawn Agent B, Revision Loop, Present Status |
+| Deploy/Release | Initialize, Validate Config, Run Deployment, Verify Health, Present Status |
+| CRUD | Initialize, Validate Entity, Persist Changes, Present Status |
+| Analysis | Initialize, Gather Context, Spawn Analyzer, Present Findings |