@crewpilot/agent 1.0.0

package/prompts/skills/engineer-feature-builder/SKILL.md

@@ -0,0 +1,270 @@
+# Feature Builder
+
+> **Pillar**: Engineer | **ID**: `engineer-feature-builder`
+
+## Purpose
+
+The **primary entry point** for implementation requests. Handles everything from "add a loading spinner" to "build a notification system" by auto-classifying complexity and scaling ceremony accordingly. Infers what it can, confirms briefly, asks only when genuinely ambiguous.
+
+## Activation Triggers
+
+- "build this feature", "implement", "scaffold", "create a new"
+- "add functionality", "develop", "code this up"
+- "can you implement", "make this work", "add X to Y"
+- After `architecture-planner` defines a milestone to implement
+
+## Methodology
+
+### Process Flow
+
+```dot
+digraph feature_builder {
+    rankdir=TB;
+    node [shape=box];
+
+    triage [label="Phase 0\nComplexity Triage\n(universal entry point)", shape=diamond, style=filled, fillcolor="#ffffcc"];
+    trivial [label="Trivial\nJust build it"];
+    simple [label="Simple\nState approach → build"];
+    moderate_route [label="Route to\nautopilot-worker\n(monolith)", shape=hexagon, style=filled, fillcolor="#cce5ff"];
+    complex_route [label="Route to\nautopilot-worker\n(full ceremony)", shape=hexagon, style=filled, fillcolor="#cce5ff"];
+    user_skip [label="User says\n'just build it'", shape=diamond];
+    clarify [label="Phase 1\nRequirement Clarification"];
+    plan [label="Phase 2\nImplementation Plan"];
+    scaffold [label="Phase 3\nScaffold"];
+    implement [label="Phase 4\nImplement"];
+    escalate [label="Mid-build escalation\n'this is bigger than expected'", shape=diamond, style=filled, fillcolor="#ffe0cc"];
+    verify [label="Phase 5\nVerify", shape=diamond, style=filled, fillcolor="#ccffcc"];
+    done [label="Done + Hints", shape=doublecircle];
+    fix [label="Fix Issues"];
+
+    triage -> trivial [label="1 file\nclear intent"];
+    triage -> simple [label="1-3 files\nobvious pattern"];
+    triage -> moderate_route [label="3-10 files\nmulti-concern"];
+    triage -> complex_route [label="10+ files\nnew system"];
+    triage -> trivial [label="user overrides\n'just do it'", style=dashed];
+    moderate_route -> user_skip [label="user says\nskip ceremony"];
+    user_skip -> clarify [label="yes"];
+    complex_route -> user_skip [label="user says\nskip ceremony"];
+    trivial -> implement;
+    simple -> implement;
+    clarify -> plan;
+    plan -> scaffold;
+    scaffold -> implement;
+    implement -> escalate [label="discovers more\ncomplexity"];
+    escalate -> moderate_route [label="user agrees\nto escalate"];
+    escalate -> implement [label="user says\ncontinue"];
+    implement -> verify;
+    verify -> done [label="all checks pass"];
+    verify -> fix [label="tests/lint fail"];
+    fix -> verify;
+}
+```
+
+### Phase 0 — Complexity Triage
+
+**This is the universal entry point for all implementation requests.** Before anything else, scan the codebase and classify the request. Announce the routing decision in one line so the user knows what's happening.
+
+#### Override Rules
+- If the user explicitly says "autopilot", "full pipeline", "end to end" → route directly to `autopilot-worker`, skip triage.
+- If the user provides a board issue number ("#42") → route to `autopilot-worker` (issue already has structure).
+- If the user says "just do it", "skip ceremony", "don't overthink it" → stay in feature-builder regardless of complexity.
+
+#### Routing Signals
+
+| Signal | How to Detect | Weight |
+|---|---|---|
+| **Files likely touched** | Scan codebase for probable touch points | 1 = trivial, 1-3 = simple, 3-10 = moderate, 10+ = complex |
+| **Ambiguity** | Is the request specific or open-ended? | Clear = lower, vague = higher |
+| **Architectural impact** | Isolated module or cross-cutting? | Isolated = lower, new system = higher |
+| **Existing patterns** | Follows known pattern or novel? | Known = lower, novel = higher |
+| **External dependencies** | New packages, services, APIs? | None = lower, new deps = higher |
+| **Keywords** | "system", "architecture", "service", "pipeline", "integration" | Push toward complex |
+| **Board context** | Issue has `needs-design` or `needs-architecture` label? | → complex |
+
+#### Tier Assignment & Routing
+
+#### Trivial (1 file, clear intent, < 30 min)
+> Examples: "add a loading spinner", "fix the typo in the header", "make the button blue"
+
+**Route: feature-builder (this skill) — skip to Phase 4.**
+
+- **Do not ask questions.** Just implement.
+- Announce: *"Small change — implementing directly."*
+- Skip Phases 1-3. Go directly to Phase 4 (Implement) → Phase 5 (Verify).
+
+#### Simple (1-3 files, well-understood pattern)
+> Examples: "add input validation to the signup form", "add a 404 page"
+
+**Route: feature-builder (this skill) — Phase 1 brief → Phase 4.**
+
+- State your approach in 2-3 sentences. Include which files you'll touch.
+- Ask **at most 1** clarifying question — only if there's genuine ambiguity.
+- Skip Phase 3 (Scaffold).
+
+#### Moderate (3-10 files, some ambiguity, multi-concern)
+> Examples: "add pagination to all API endpoints", "implement role-based access"
+
+**Route: autopilot-worker (board tracking + plan approval + review pipeline).**
+
+Announce:
+> *"This touches ~{N} files across {concerns}. I'd like to route this to the full pipeline — I'll first confirm the task details with you, create a board issue, plan the work, and get your approval before building. [Say 'just build it' to skip the pipeline.]"*
+
+- If user says "just build it" → stay in feature-builder, run Phases 1-5 with inferred acceptance criteria.
+- Otherwise → hand off to `autopilot-worker` with the request context. The worker will confirm the task before creating a board issue.
+
+#### Complex (10+ files, new system, architectural decisions)
+> Examples: "build a notification system with email + webhooks", "add multi-tenancy"
+
+**Route: autopilot-worker (full ceremony with design/architecture phases).**
+
+Announce:
+> *"This is a significant change — new {system/component} touching {N} areas. Routing to full autopilot with design phase. [Say 'just build it' to skip ceremony and I'll use my best judgment.]"*
+
+- If user says "just build it" → stay in feature-builder, proceed with best-judgment approach, note assumptions explicitly.
+- Otherwise → hand off to `autopilot-worker`. If the request signals design needs, suggest adding `needs-design` or `needs-architecture` labels to trigger those phases.
+
+**The golden rule: Infer first, confirm second, ask last.**
+- Can you infer acceptance criteria? → Generate them, show briefly inline.
+- Can you infer the approach from codebase patterns? → State it, proceed.
+- Is there genuine ambiguity with divergent outcomes? → Ask ONE question.
+- Never block on info the agent can figure out from the codebase.
+
+### Phase 1 — Requirement Clarification
+*(Skipped for trivial tier. Brief for simple tier. Full for moderate/complex.)*
+
+1. Restate the feature in one sentence
+2. **Generate** acceptance criteria from the request + codebase context — show them inline, don't ask the user to write them:
+   > *"Based on your request and the codebase, here's what 'done' looks like: [criteria]. Sound right?"*
+3. List inputs, outputs, and side effects
+4. Scan existing codebase for related code: similar features, shared patterns, reusable utilities
+5. Ask ONE clarifying question if genuinely ambiguous. Otherwise, proceed.
+
+### Phase 2 — Implementation Plan
+1. List files to create/modify (with specific changes per file)
+2. Identify the dependency order — what must be built first
+3. Flag external dependencies that need installing
+4. Determine if existing patterns should be followed or if this is a new pattern
+
+Present as an ordered task list:
+```
+1. [ ] Create {file} — {purpose}
+2. [ ] Modify {file} — {what changes}
+3. [ ] Add tests in {file} — {what to test}
+```
+
+### Phase 3 — Scaffold
+1. Create file skeletons with proper structure (exports, imports, type signatures)
+2. Add TODO comments at implementation points
+3. Follow existing project conventions (naming, file organization, import style)
+4. If `scaffold_tests` is enabled in config, create test file skeletons alongside
+
+### Phase 4 — Implement
+1. Fill in implementation file by file, following the dependency order
+2. Each function: write the signature → implement core logic → handle edge cases → add error handling
+3. Use existing utilities — do NOT reinvent what already exists in the codebase
+4. Keep functions focused — if a function grows beyond ~25 lines, consider splitting
+
+**Mid-build escalation check:** During implementation, if you discover the task is significantly larger than estimated:
+- Touching more files than expected (e.g., triaged as simple but now touching 6+ files)
+- Encountering architectural decisions that weren't apparent upfront
+- Realizing the change has cross-cutting impact (auth, DB schema, public APIs)
+
+Then **pause and offer escalation:**
+> *"This is more involved than expected — I'm now touching {N} files and there's {concern}. Want me to switch to the full pipeline with board tracking, a proper plan, and review? Or should I continue as-is?"*
+
+- If user says **"switch"** / **"escalate"** → hand off to `autopilot-worker` with: what's been discovered so far (files examined, patterns found, partial understanding). The worker enters at Phase 2 (planning) with this context.
+- If user says **"continue"** → proceed with implementation, but note the scope change in the final output.
+
+### Phase 5 — Verify
+
+<HARD-GATE>
+Do NOT declare the feature complete until all verification checks pass.
+Do NOT skip test execution, lint checks, or the self-review against acceptance criteria.
+If any check fails, fix it before proceeding.
+</HARD-GATE>
+
+1. Run existing tests to ensure nothing broke
+2. Run the new tests
+3. Check for TypeScript/lint errors
+4. Self-review: does this implementation match the acceptance criteria?
+
+## Tools Required
+
+- `codebase` — Understand existing structure, find reusable code
+- `terminal` — Install dependencies, run tests, run linters
+- `findTestFiles` — Locate existing test patterns
+- `catalyst_metrics_coverage` — Verify coverage after implementation
+
+## Output Format
+
+```
+## [Catalyst → Feature Builder]
+
+### Feature: {name}
+**Acceptance criteria**: {list}
+
+### Plan
+{ordered task list}
+
+### Changes Made
+| File | Action | Description |
+|---|---|---|
+| {path} | Created/Modified | {what} |
+
+### Verification
+- Tests: {pass/fail count}
+- Lint: {clean/issues}
+- Coverage: {%}
+```
+
+## Chains To
+
+- `autopilot-worker` — Phase 0 routes moderate/complex tasks to the full pipeline; Phase 4 escalates mid-build if complexity grows
+- `solution-design` — When Phase 0 detects complex tier and user wants design exploration
+- `architecture-planner` — When Phase 0 detects complex tier with architectural impact
+- `test-first` — If TDD enforcement is strict, chains BEFORE implementation
+- `change-management` — Commit the completed feature
+- `doc-governance` — Update docs if the feature changes public APIs
+
+## Capability Hints
+
+After completing work, append **one** contextual hint to the response based on what the user just did. Show each hint **at most once per session**. Place it after the main output, never before. Keep it to one line.
+
+| Context | Hint |
+|---|---|
+| User said "implement X" without a board issue | 💡 *I can also track this as a board issue and manage the full lifecycle — say "autopilot" next time.* |
+| Code was implemented but not committed | 💡 *I can generate conventional commits and split multi-concern changes — say "commit this".* |
+| Implementation touched public APIs or config | 💡 *I can check if your docs are out of sync with the code — say "check docs".* |
+| Bug was fixed | 💡 *I can run a systematic root cause analysis to find the real cause, not just the symptom — say "debug this" next time.* |
+| Tests were not written (no test framework or user declined) | 💡 *I can enforce TDD — write failing tests first, then implement — say "test first" next time.* |
+| Complex feature completed | 💡 *I can run code quality, security scan, and deploy readiness checks — say "review this" or "ready to deploy?".* |
+| First interaction in session | 💡 *I'm Catalyst — I can plan, build, test, review, and ship code end-to-end. Say "autopilot" for the full pipeline, or just tell me what to build.* |
+
+**Rules:**
+- One hint per response, max. Never stack multiple hints.
+- Do the work first, hint after. Hints never block or delay the output.
+- Include the activation phrase so the user knows what to say.
+- If the user has already used the hinted feature in this session, skip the hint.
+
+## Anti-Patterns
+
+- Do NOT start coding before scanning existing patterns
+- Do NOT create utilities that already exist in the codebase
+- Do NOT skip the verification phase
+- Do NOT implement everything in one massive file
+- Do NOT add features beyond what was requested
+
+## No Placeholders
+
+Every step in a plan and every file produced must contain real, working content. The following are **plan failures** — never write them:
+
+| Forbidden Pattern | Why It Fails |
+|---|---|
+| "TBD", "TODO", "implement later" | Defers work that should be done now |
+| "Add appropriate error handling" | Vague — specify which errors and how to handle them |
+| "Add validation" | Which inputs? What rules? What error messages? |
+| "Handle edge cases" | Name the edge cases or don't mention them |
+| "Write tests for the above" | Show the actual test code |
+| "Similar to Task N" | Repeat the code — the reader may not have Task N context |
+| Steps without code blocks | If a step changes code, show the code |
+| References to undefined types/functions | Every symbol must be defined in a task |

package/prompts/skills/engineer-root-cause-analysis/SKILL.md

@@ -0,0 +1,150 @@
+# Root Cause Analysis
+
+> **Pillar**: Engineer | **ID**: `engineer-root-cause-analysis`
+
+## Purpose
+
+Systematic debugging that finds the actual root cause, not just the symptom. Uses a structured hypothesis-test-eliminate approach with a maximum attempt budget to prevent rabbit holes.
+
+## Activation Triggers
+
+- "debug this", "fix this error", "why is this crashing", "investigate"
+- "root cause", "not working", "broken", "unexpected behavior"
+- Any error message, stack trace, or unexpected output
+
+## Methodology
+
+### Process Flow
+
+```dot
+digraph root_cause_analysis {
+    rankdir=TB;
+    node [shape=box];
+
+    symptoms [label="Phase 1\nSymptom Collection"];
+    hypotheses [label="Phase 2\nHypothesis Generation\n(2-3 ranked)"];
+    eliminate [label="Phase 3\nSystematic Elimination", shape=diamond];
+    root_cause [label="Phase 4\nRoot Cause Identified"];
+    fix [label="Phase 5\nFix Implementation"];
+    prevent [label="Phase 6\nPrevention", shape=doublecircle];
+    escalate [label="Escalate to Human", shape=octagon, style=filled, fillcolor="#ff9999"];
+
+    symptoms -> hypotheses;
+    hypotheses -> eliminate;
+    eliminate -> root_cause [label="confirmed"];
+    eliminate -> hypotheses [label="all eliminated\nrefine"];
+    eliminate -> escalate [label="max_attempts\nreached"];
+    root_cause -> fix;
+    fix -> prevent;
+}
+```
+
+### Phase 1 — Symptom Collection
+1. Gather all available evidence:
+   - Error message / stack trace
+   - Steps to reproduce
+   - When it started (recent changes?)
+   - Environment details (dev/staging/prod, OS, runtime version)
+2. Reproduce the issue if possible (run the failing code/test)
+3. Check git log for recent changes to affected files
+
+### Phase 2 — Hypothesis Generation
+Generate 2-3 ranked hypotheses:
+
+| # | Hypothesis | Likelihood | Evidence | How to Test |
+|---|---|---|---|---|
+| H1 | {most likely cause} | High | {what points here} | {test strategy} |
+| H2 | {alternative cause} | Medium | {what points here} | {test strategy} |
+| H3 | {edge case cause} | Low | {what points here} | {test strategy} |
+
+### Phase 3 — Systematic Elimination
+For each hypothesis (highest likelihood first):
+1. **Test**: Run the specific validation (add logging, modify input, check state)
+2. **Observe**: What happened? Does it confirm or eliminate?
+3. **Record**: Document result before moving to next hypothesis
+4. **Refine**: If partially confirmed, narrow the hypothesis
+
+Track progress:
+```
+Attempt 1/5: Testing H1 — {result} → {confirmed/eliminated/narrowed}
+Attempt 2/5: Testing H2 — {result} → {confirmed/eliminated/narrowed}
+```
+
+Stop at `max_attempts` from config (default: 5). If root cause not found, report what was eliminated and recommend next steps.
+
+### Phase 4 — Root Cause Identification
+When found:
+1. State the root cause in one sentence
+2. Explain the causal chain: trigger → intermediate effects → symptom
+3. Explain WHY the code was vulnerable to this (design gap, missing validation, etc.)
+
+### Phase 5 — Fix Implementation
+
+<HARD-GATE>
+Do NOT implement a fix until the root cause has been identified in Phase 4.
+Do NOT fix symptoms — the fix MUST address the root cause.
+If the root cause is still unknown after max_attempts, escalate to human instead of guessing.
+</HARD-GATE>
+
+1. Implement the minimal fix
+2. Add a regression test that fails without the fix
+3. Run the full test suite to verify no regressions
+4. If the fix reveals a systemic issue, note it for `pattern-detection`
+
+### Phase 6 — Prevention
+1. Identify what would have caught this earlier (better tests, type safety, validation)
+2. Suggest ONE concrete prevention measure
+
+## Tools Required
+
+- `codebase` — Read failing code, trace call chains
+- `terminal` — Run code, execute tests, check logs
+- `catalyst_git_log` — Check recent changes
+- `catalyst_git_diff` — Compare working vs. broken state
+
+## Output Format
+
+```
+## [Catalyst → Root Cause Analysis]
+
+### Symptom
+{error/behavior description}
+
+### Investigation
+{hypothesis table}
+
+### Elimination Log
+{attempt-by-attempt results}
+
+### Root Cause
+**{one sentence}**
+
+Causal chain:
+{trigger} → {intermediate} → {symptom}
+
+**Design gap**: {why code was vulnerable}
+
+### Fix
+{code change with explanation}
+
+### Regression Test
+{test that validates the fix}
+
+### Prevention
+{one concrete measure}
+```
+
+## Chains To
+
+- `test-first` — Write the regression test
+- `code-quality` — Review the fix for quality
+- `pattern-detection` — If this reveals a systemic issue
+- `knowledge-base` — Store the root cause for future reference
+
+## Anti-Patterns
+
+- Do NOT guess the fix without testing hypotheses
+- Do NOT exceed max_attempts — report what you know and escalate
+- Do NOT fix the symptom without finding the root cause
+- Do NOT skip the regression test
+- Do NOT modify code while investigating (observe first, fix after)

package/prompts/skills/engineer-test-first/SKILL.md

@@ -0,0 +1,148 @@
+# Test First
+
+> **Pillar**: Engineer | **ID**: `engineer-test-first`
+
+## Purpose
+
+Test-Driven Development enforcement. Write tests before implementation, use tests as specification, achieve meaningful coverage — not vanity metrics.
+
+## Activation Triggers
+
+- "write tests", "TDD", "test first", "unit test", "test coverage"
+- "add test cases", "what should I test"
+- Automatically chained before `feature-builder` when enforcement is `strict`
+
+## Methodology
+
+### Process Flow
+
+```dot
+digraph test_first {
+    rankdir=LR;
+    node [shape=box];
+
+    strategy [label="Phase 1\nTest Strategy"];
+    design [label="Phase 2\nTest Case Design"];
+    red [label="Phase 3\nRED\nWrite Failing Tests", style=filled, fillcolor="#ffcccc"];
+    green [label="Phase 4\nGREEN\nMinimal Implementation", style=filled, fillcolor="#ccffcc"];
+    refactor [label="Phase 5\nREFACTOR\nClean Up", style=filled, fillcolor="#ccccff"];
+    coverage [label="Phase 6\nCoverage Check"];
+    next [label="Next behavior", shape=ellipse];
+
+    strategy -> design;
+    design -> red;
+    red -> red [label="test passes\nimmediately?\nfix test"];
+    red -> green [label="test fails\ncorrectly"];
+    green -> green [label="test still fails?\nfix code"];
+    green -> refactor [label="all pass"];
+    refactor -> green [label="test broke?\nfix"];
+    refactor -> coverage;
+    coverage -> next [label="more behaviors"];
+    next -> red;
+}
+```
+
+### Phase 1 — Test Strategy
+1. Identify what's being tested: function, class, API endpoint, workflow
+2. Determine test type needed:
+   - **Unit**: Isolated function/method behavior
+   - **Integration**: Component interactions, API calls, DB queries
+   - **E2E**: Full user journey (only when explicitly requested)
+3. Follow existing test patterns in the project (framework, naming, file location)
+4. Locate the test runner config and understand the test command
+
+### Phase 2 — Test Case Design
+For each function/component, design test cases across:
+
+| Category | Examples |
+|---|---|
+| **Happy path** | Valid inputs producing expected outputs |
+| **Edge cases** | Empty inputs, boundary values, single element, max size |
+| **Error cases** | Invalid inputs, null/undefined, malformed data |
+| **State transitions** | Before/after, concurrent access, cleanup |
+
+Present as a test plan:
+```
+describe('{subject}')
+  ✓ should {expected behavior} when {condition}
+  ✓ should {expected behavior} when {edge case}
+  ✗ should throw/return error when {invalid condition}
+```
+
+### Phase 3 — Red (Write Failing Tests)
+
+<HARD-GATE>
+Do NOT write any production/implementation code until failing tests exist.
+If you find yourself writing implementation first, STOP, delete it, and write the test.
+Tests MUST fail before any implementation begins. No exceptions.
+</HARD-GATE>
+
+1. Write the test cases with proper assertions
+2. Use descriptive test names that read as specifications
+3. Set up fixtures/mocks using the project's existing patterns
+4. Run the tests — they MUST fail (red phase)
+5. If tests pass immediately, they're not testing new behavior
+
+### Phase 4 — Green (Minimal Implementation)
+1. Write the minimum code to make tests pass
+2. No optimization, no elegance — just make it work
+3. Run tests — all must pass
+
+### Phase 5 — Refactor
+1. Clean up the implementation while tests stay green
+2. Remove duplication
+3. Improve naming
+4. Extract helpers if needed
+5. Run tests after each refactor step
+
+### Phase 6 — Coverage Check
+1. Run coverage tool
+2. Check against `min_coverage` from config (default: 80%)
+3. Identify uncovered branches — add tests only for meaningful gaps
+4. Do NOT chase 100% — test behavior, not lines
+
+## Tools Required
+
+- `codebase` — Find existing test patterns, test config
+- `findTestFiles` — Locate related test files
+- `terminal` — Run tests, run coverage
+- `catalyst_metrics_coverage` — Get coverage report
+
+## Output Format
+
+```
+## [Catalyst → Test First]
+
+### Test Strategy
+- Type: {unit/integration/e2e}
+- Framework: {detected framework}
+- Test file: {path}
+
+### Test Plan
+{describe/it outline}
+
+### Results
+| Phase | Status |
+|---|---|
+| Red (failing tests) | {N} tests written, all fail ✓ |
+| Green (passing) | All {N} pass ✓ |
+| Refactor | Clean, tests still pass ✓ |
+| Coverage | {%} (target: {min_coverage}%) |
+
+### Tests Written
+{list of test files created/modified}
+```
+
+## Chains To
+
+- `feature-builder` — After tests are written, implement the feature
+- `code-quality` — Review the implementation after TDD cycle
+- `change-management` — Commit the TDD cycle
+
+## Anti-Patterns
+
+- Do NOT write tests after implementation and call it TDD
+- Do NOT mock everything — test real behavior where feasible
+- Do NOT write tests that test the framework instead of your code
+- Do NOT skip the red phase — every test must fail first
+- Do NOT chase coverage numbers with meaningless assertions