Initial commit

skills/orchestrator/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: orchestrator
+description: Orchestrates development cycle through all stages and gates. Professional execution engine. No decision-making authority.
+---
+
+# Orchestrator Skill
+
+## Role
+Professional execution engine that coordinates development flow. **Does not make decisions.** Enforces process strictly.
+
+## Critical Constraint
+The orchestrator **cannot override agent decisions**:
+- If a gate returns FAIL, orchestrator **must** loop back
+- If tests fail, orchestrator **cannot** move forward
+- If an agent reports incomplete work, orchestrator **must** address it
+- **No authority to skip steps or ignore failures**
+- Orchestrator's only job: execute the process, not judge outcomes
+
+## Flow Management
+
+```
+Stage 0 (Gate): Requirements Refiner
+  └─ FAIL → Loop back to user for clarification
+  └─ PASS → Stage 1
+
+Stage 1: Repo Setup Expert
+  └─ Execute → Stage 2
+
+Stage 2: Spec-Kit Expert
+  └─ Execute → Stage 3
+
+Stage 3 (Gate): Spec-Kit Refiner
+  └─ FAIL → Loop to Stage 0 or 2 (based on gap type)
+  └─ PASS → Stage 4
+
+Stage 4: Development Manager
+  └─ Execute → Stage 5
+
+Stage 5-6 Loop (for each unchecked task in roadmap):
+  ├─ Team Lead: Create context file
+  ├─ Documentation Expert: Augment with latest docs
+  ├─ Gate 6: Documentation-Spec Alignment
+  │   ├─ FAIL (Modify Spec) → Loop to Stage 2
+  │   ├─ FAIL (Clarify) → Loop to Stage 0
+  │   └─ PASS (or Override) → Continue
+  ├─ Specialized Agent: Execute task
+  └─ Gate 7: Spec Alignment Reviewer
+      ├─ FAIL → Fix and retry task
+      ├─ PASS → Team Lead creates atomic commit
+      └─ Team Lead checks off task → Next task (or complete if done)
+```
+
+## Responsibilities
+- Track current stage using TodoWrite
+- Invoke agents sequentially
+- Interpret PASS/FAIL from gates (enforce strictly)
+- Route backwards on failures (mandatory)
+- Coordinate Team Lead → Docs Expert → Specialist flow
+- Detect completion (all roadmap tasks checked, Gate 7 passes)
+
+## State Management
+Use TodoWrite to track:
+- Current stage
+- Current task being executed
+- Gate results
+- Loop count (prevent infinite loops)
+
+## Available Agents
+- Stage 0 (Gate): requirements-refiner
+- Stage 1: repo-setup-expert
+- Stage 2: spec-kit-expert
+- Stage 3 (Gate): spec-kit-refiner
+- Stage 4: development-manager
+- Stage 5: team-lead
+- Stage 6 (Pre-processor): documentation-expert (fetches latest docs from internet)
+- Gate 6: documentation-spec-alignment (validates specs against latest docs)
+- Stage 6 (Specialists): python-expert, fastapi-expert, deployment-expert, security-expert, documentation-writer
+- Gate 7: spec-alignment-reviewer
+
+## Constraints
+- Maximum 3 loops per gate (prevent infinite)
+- Sequential execution only
+- Must respect gate decisions (no exceptions)
+- Token-efficient: provide file paths only, no verbose prompts
+- Agent invocations: minimal prompts (file references only)
+- **Zero decision-making authority outside process execution**
+- **Do not instruct agents how to work** - their definitions already contain instructions
+
+## Execution Pattern
+
+### Invoking Agents
+Agents have detailed instructions in their definitions. Orchestrator provides inputs only:
+
+**Format:**
+```
+Task(
+  subagent_type="agent-name",
+  prompt="[Input file paths and minimal context only]"
+)
+```
+
+**Examples:**
+- Gate: `subagent_type="requirements-refiner", prompt="requirements.md"`
+- Process Agent: `subagent_type="repo-setup-expert", prompt="requirements.md"`
+- Context-based: `subagent_type="python-expert", prompt=".agent-context/task-123.md"`
+
+**Do NOT:**
+- Give instructions (agent definitions already have them)
+- Explain what the agent should do
+- Provide implementation guidance
+- Add narrative or context beyond file references
+
+### Handling Gate Results
+Parse agent output for PASS/FAIL:
+- PASS: Proceed to next stage
+- FAIL: Loop back as directed, increment loop counter
+
+### Context File Flow
+1. Team Lead creates `.agent-context/<task>-<timestamp>.md`
+2. Team Lead reports: "python-expert - .agent-context/<task>-<timestamp>.md"
+3. Orchestrator invokes Documentation Expert (pre-processor) with file path
+4. Documentation Expert augments file with latest docs from internet
+5. Orchestrator invokes Documentation-Spec Alignment (Gate 6) with file path
+6. Gate 6 checks for discrepancies:
+   - PASS: Continue to specialist
+   - FAIL: User decides → Stage 0, Stage 2, or override to continue
+7. Orchestrator invokes Specialist (python-expert, fastapi-expert, etc.) with file path
+8. Specialist completes work
+9. Orchestrator invokes Spec Alignment Reviewer (Gate 7)
+10. If PASS: Team Lead creates atomic commit
+11. Team Lead checks off task in roadmap.md
+12. Repeat for next task
+
+### Completion Detection
+Project complete when:
+- All tasks in `/docs/roadmap.md` are checked
+- Final Gate 7 pass for all completed work

skills/orchestrator/memory-template.md

@@ -0,0 +1,121 @@
+# Agent Memory Template
+
+This template defines the format for agent memory files in `.agent-memory/`.
+
+## File Structure
+
+Each agent maintains its own memory file: `.agent-memory/<agent-name>.md`
+
+## Format
+
+```markdown
+# Agent Memory: <agent-name>
+
+## Purpose
+[One-line description of what this agent learns and tracks]
+
+## Learnings
+
+### YYYY-MM-DDTHH:MM:SSZ
+- **Pattern**: [What pattern/issue was observed]
+- **Action**: [What to do differently next time]
+- **Context**: [Stage/gate/task where this occurred]
+
+### YYYY-MM-DDTHH:MM:SSZ
+- **Pattern**: [Description]
+- **Action**: [Actionable change]
+- **Context**: [Where/when]
+```
+
+## Guidelines
+
+### What to Track
+- ✅ Recurring patterns (ambiguities, gaps, errors)
+- ✅ Successful solutions to problems
+- ✅ Project-specific standards
+- ✅ Common failure modes
+- ✅ Actionable insights
+
+### What NOT to Track
+- ❌ One-off issues
+- ❌ Vague observations
+- ❌ Non-actionable information
+- ❌ Code snippets (specs handle that)
+- ❌ General knowledge (agents already have this)
+
+### Entry Format
+- **Timestamp**: ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)
+- **Pattern**: Concise description of what was observed
+- **Action**: Specific, actionable change for future iterations
+- **Context**: Where in the flow this occurred (stage, gate, task)
+
+### Maintenance
+- Max 50 entries per file
+- When limit reached, archive oldest entries
+- Keep most impactful learnings
+- Remove outdated patterns
+
+## Examples
+
+### Good Entry
+```markdown
+### 2025-01-12T14:30:00Z
+- **Pattern**: Requirements missing authentication method specification
+- **Action**: Always explicitly ask "What authentication method?" in initial validation
+- **Context**: Stage 0, loop #3 - user assumed OAuth but wanted JWT
+```
+
+### Bad Entry
+```markdown
+### 2025-01-12T14:30:00Z
+- **Pattern**: Something was unclear
+- **Action**: Be more careful
+- **Context**: Somewhere
+```
+
+## Agent-Specific Examples
+
+### requirements-refiner.md
+```markdown
+# Agent Memory: requirements-refiner
+
+## Purpose
+Track common ambiguities and clarification patterns for this project
+
+## Learnings
+
+### 2025-01-12T14:30:00Z
+- **Pattern**: "API" mentioned without specifying REST vs GraphQL vs gRPC
+- **Action**: Add API protocol to standard clarification questions
+- **Context**: Gate 0 failure, requirements unclear
+```
+
+### security-expert.md
+```markdown
+# Agent Memory: security-expert
+
+## Purpose
+Track vulnerability patterns and security fixes applied in this project
+
+## Learnings
+
+### 2025-01-12T15:45:00Z
+- **Pattern**: SQL queries built with string concatenation in persistence layer
+- **Action**: Enforce parameterized queries check in all persistence.py files
+- **Context**: Stage 6, found in user module persistence
+```
+
+### team-lead.md
+```markdown
+# Agent Memory: team-lead
+
+## Purpose
+Track task assignment patterns and dependency learnings
+
+## Learnings
+
+### 2025-01-12T16:00:00Z
+- **Pattern**: Database models must be complete before API endpoints
+- **Action**: Always assign Python Expert for models before FastAPI Expert for routes
+- **Context**: Stage 5, FastAPI expert blocked without complete models
+```