@nlaprell/shipit 1.0.0

package/.cursor/commands/test_shipit.md

@@ -0,0 +1,197 @@
+# /test_shipit
+
+Run the ShipIt end-to-end test plan. (Slash command: use the same name as this file, e.g. `/test_shipit`.)
+
+## Mode Detection
+
+**Check for `project.json` in current directory:**
+
+- **If `project.json` exists AND contains `"name": "shipit-test"`:** You are in the TEST PROJECT. Start at step 2-2.
+- **If `project.json` exists BUT name is NOT `shipit-test`:** STOP and report a blocking failure (wrong workspace).
+- **Otherwise:** You are in the ROOT PROJECT. Run steps 1-1 through 1-4, then STOP.
+
+**Note:** The test project is now created at `./tests/test-project` (not `./projects/shipit-test`). Mode detection checks for `tests/test-project/project.json` with name "shipit-test".
+
+## Root Project Mode (Steps 1-1 → 1-4)
+
+### Before Starting
+
+If `./tests/test-project` already exists, DELETE IT:
+
+```bash
+rm -rf ./tests/test-project
+```
+
+### GitHub Issue Tracking Preflight (Required)
+
+This test plan records issues on GitHub (not in local files). Before running steps, verify `gh` is available and authenticated:
+
+```bash
+gh --version
+gh auth status
+```
+
+If this fails, **STOP** and treat it as a **blocking** failure (issues cannot be recorded correctly). Follow `_system/behaviors/WORK_TEST_PLAN_ISSUES.md`.
+
+If `_system/behaviors/WORK_TEST_PLAN_ISSUES.md` is not present in your current workspace, use `./scripts/create-test-plan-issue.sh` to file issues with consistent formatting.
+
+### Where to Record Results
+
+Root mode results must be written to `tests/ISSUES.md` (root ShipIt project).
+
+**Important:** `tests/ISSUES.md` is **test run logging only**. Any failures that represent real issues must be created as **GitHub issues** per `_system/behaviors/WORK_TEST_PLAN_ISSUES.md`, and the run should reference them by GitHub issue number.
+
+### Guardrails
+
+Before starting, verify the file exists:
+
+- `tests/fixtures.json`
+
+If missing, STOP and log a **blocking** failure.
+
+### Execute Steps
+
+**Step 1-1:** Initialize the test project (non-interactive using fixtures)
+
+The script now automatically reads from `tests/fixtures.json` and creates the test project at `./tests/test-project`.
+
+Run:
+
+```bash
+rm -rf ./tests/test-project
+./scripts/init-project.sh shipit-test
+```
+
+**Step 1-2:** (Covered by Step 1-1) Verify the init used the exact fixture inputs from `tests/fixtures.json`.
+
+**Step 1-3:** Verify `./tests/test-project` was created
+
+**Step 1-4:** Verify these files exist in the new project:
+
+- `project.json`
+- `package.json`
+- `tsconfig.json`
+- `work/intent/_TEMPLATE.md`
+- `_system/architecture/CANON.md`
+- `work/roadmap/now.md`, `next.md`, `later.md`
+
+### STOP HERE
+
+After step 1-4 passes, output this message:
+
+```
+✅ Root project steps complete (1-1 through 1-4).
+
+NEXT: Open ./tests/test-project in a NEW Cursor window, then run /test_shipit from there to continue testing.
+```
+
+**DO NOT continue to step 2. The user must open the test project in a separate workspace.**
+
+---
+
+## Test Project Mode (Steps 2-2 → 24)
+
+**In-scope:** All steps in `tests/TEST_PLAN.md` from 2-2 through 24. Do NOT stop at step 10. Continue through commands (11-15), full /ship cycle (16-21), and validation (22-24) until completion or a blocking failure.
+
+### Load Test Fixtures
+
+Read `tests/fixtures.json` (or the framework's `tests/fixtures.json` if running from test project) for hardcoded inputs.
+
+### GitHub Issue Tracking Preflight (Required)
+
+Before executing steps, verify `gh` is available and authenticated:
+
+```bash
+gh --version
+gh auth status
+```
+
+If this fails, **STOP** and treat it as a **blocking** failure. Follow `_system/behaviors/WORK_TEST_PLAN_ISSUES.md` (includes repo resolution rules).
+
+If `_system/behaviors/WORK_TEST_PLAN_ISSUES.md` is not present in your current workspace, use `./scripts/create-test-plan-issue.sh` to file issues with consistent formatting.
+
+### Execute Steps
+
+Follow `tests/TEST_PLAN.md` starting from step 2-2.
+
+**Use these hardcoded inputs:**
+
+| Step | Input                                                                                                                                         |
+| ---- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| 3-1  | Scope: `"Build a todo list app with CRUD, tagging, and persistence"`                                                                          |
+| 3-2  | Follow-ups: API-only, JSON file, Single-user, auth none. Select all features.                                                                 |
+| 4-1  | Intent: `"Add due dates to todos"` (feature), priority=2, effort=2, release=2, deps=none, risk=2                                              |
+| 7-2  | Update F-001: priority=p0, effort=s, release_target=R1                                                                                        |
+| 8-1  | F-001 deps: `- F-002`, F-002 deps: `(none)`                                                                                                   |
+| 9-1  | Add `- F-999` to F-001 dependencies                                                                                                           |
+| 10-1 | Create intent: `"Awesome Banner"` (feature), priority=4, effort=1, release=4, deps=none, risk=1                                               |
+| 15-1 | Create disposable intent for kill: type=1, title=`Temporary kill intent`, motivation=done, priority=4, effort=1, release=4, deps=none, risk=1 |
+
+**Non-interactive intent creation (recommended for test runs):**
+
+```bash
+printf "1\nAdd due dates to todos\nImprove prioritization for users\nSupport basic deadline tracking\ndone\n2\n2\n2\nnone\n2\n" | ./scripts/new-intent.sh
+printf "1\nAwesome Banner\nDisplay a graphical banner at the top of the project README\ndone\n4\n1\n4\nnone\n1\n" | ./scripts/new-intent.sh
+# Step 15-1: disposable intent for /kill
+printf "1\nTemporary kill intent\ndone\n4\n1\n4\nnone\n1\n" | ./scripts/new-intent.sh
+```
+
+### After Each Step
+
+1. Record result (PASS/FAIL)
+2. If FAIL, determine severity:
+   - `blocking` — stops subsequent tests
+   - `high` — core functionality broken
+   - `medium` — works incorrectly
+   - `low` — minor/cosmetic
+3. Append the step result to the current run block in `tests/ISSUES.md`
+4. If the failure indicates a real bug/tooling gap, create a GitHub issue per `_system/behaviors/WORK_TEST_PLAN_ISSUES.md` and reference it by issue number in the run block
+
+### Fail-Fast Rule
+
+If a step fails with `blocking` severity, STOP testing immediately. Do not continue to subsequent steps.
+
+**Blocking failures include:**
+
+- Project initialization fails (can't create project)
+- Required files missing after init
+- Scripts fail to execute
+- Core generation commands produce no output
+
+When stopping early, mark all remaining steps as `⏭️ SKIP` with reason: `Blocked by step X-Y`.
+
+### On Completion
+
+Output summary in this shape. Include a short phase summary so the run is scannable; point explicitly to per-step details.
+
+```
+## Test Run Complete
+
+**Date:** [ISO timestamp]
+**Mode:** test-project
+**Steps Total:** X
+**Steps Executed:** Y
+**Steps Skipped:** Z
+**Steps Passed:** A
+**Steps Failed:** B
+**Blocking Issues:** N
+**Result:** PASS | FAIL
+
+**Phase summary:** Setup ✓ | Planning ✓ | Commands ✓ | Full cycle ✓ | Validation ✓  (or mark failed phases)
+
+Per-step results and any issue references are in **tests/ISSUES.md**.
+```
+
+---
+
+## ISSUES.md Update Rules
+
+After each test run:
+
+1. **Rotate prior runs to historic:** Move all existing run blocks from `tests/ISSUES.md` to `tests/ISSUES_HISTORIC.md` (append under `## Historic Test Runs`). Keep the header and Counting Conventions in ISSUES.md.
+2. **Write only the new run:** Replace `tests/ISSUES.md` content with the header, Counting Conventions, and **only the latest run block** (the one you just completed).
+3. **Include "Issues Found This Run"** in the new run block, referencing GitHub issue numbers (e.g., `#123`).
+
+**Rule:** `tests/ISSUES.md` must contain **only the latest run**. All prior runs live in `tests/ISSUES_HISTORIC.md`.
+
+See `.cursor/rules/test-runner.mdc` for detailed formatting rules.

package/.cursor/commands/verify.md

@@ -0,0 +1,50 @@
+# /verify
+
+Run verification phase only (Phase 5 of /ship workflow).
+
+## Usage
+
+```
+/verify <intent-id>
+```
+
+Example: `/verify F-042`
+
+## What It Does
+
+Runs the verification phase without going through the full /ship workflow:
+
+1. **QA Verification:**
+   - Run all tests: `pnpm test`
+   - Run mutation testing: `pnpm test:mutate` (Stryker)
+   - Try to break the implementation
+   - Document findings
+
+2. **Security Verification:**
+   - Review for auth/input/secrets/PII issues
+   - Run `pnpm audit --audit-level=high` for dependency vulnerabilities
+   - Check high-risk domains
+
+3. **Save Results:**
+   - Output to `work/workflow-state/04_verification.md`
+
+## Script
+
+Run:
+
+```bash
+./scripts/verify.sh <intent-id>
+```
+
+## When to Use
+
+- Re-running verification after fixes
+- Verifying existing code before changes
+- Pre-release validation
+
+## Role Switching
+
+This command uses the same role-switching pattern as `/ship`:
+
+- Switch to QA role for test verification
+- Switch to Security role for security review

package/.cursor/rules/architect.mdc

@@ -0,0 +1,84 @@
+---
+description: Architect Agent - System design, constraint enforcement, ADRs
+globs:
+  - "_system_system/architecture/**"
+  - "work/work/workflow-state/02_plan.md"
+alwaysApply: false
+---
+
+# Architect Agent
+
+You are the **Architect** agent—responsible for system design and constraint enforcement.
+
+## Your Role
+
+- **Purpose:** Prevent architectural drift
+- **Outputs:** CANON.md updates, ADRs, design proposals
+- **Key Function:** Ensure designs respect system boundaries
+
+## What You Do
+
+1. **Propose technical approach** (how to implement the intent)
+2. **List files to create/modify** (explicit file list)
+3. **Check against CANON.md** (must not violate boundaries)
+4. **Define rollback strategy** (how to undo if needed)
+5. **Check _system/do-not-repeat/** before proposing designs
+
+## Before Proposing Design
+
+1. Read `_system/architecture/CANON.md` (system boundaries)
+2. Read `_system/architecture/invariants.yml` (hard constraints)
+3. Read `_system/do-not-repeat/abandoned-designs.md`
+4. Read `_system/do-not-repeat/failed-experiments.md`
+5. Check existing ADRs in `_system/architecture/ADR-###.md`
+
+## Design Proposal Format
+
+Save to `work/workflow-state/02_plan.md`:
+
+```markdown
+# Plan: F-###: Title
+
+## Technical Approach
+- Approach point 1
+- Approach point 2
+
+## Files to Create/Modify
+- `src/domain/user.ts` (new)
+- `src/services/auth.ts` (modify)
+- `tests/user.test.ts` (new)
+
+## CANON.md Compliance
+- ✅ No circular dependencies
+- ✅ Respects layer boundaries
+- ✅ No forbidden patterns
+
+## Rollback Strategy
+- Feature flag: `FEATURE_X_ENABLED=false`
+- Revert commit: `git revert <sha>`
+- Database: down migration exists
+
+## Do-Not-Repeat Check
+- [ ] No similar abandoned designs
+- [ ] No similar failed experiments
+```
+
+## What You Cannot Do
+
+- Implement beyond scaffolding (that's Implementer's job)
+- Write production code
+- Change architecture canon without ADR
+
+## ADR Requirements
+
+If your design changes architecture canon, you MUST:
+1. Create `_system/architecture/ADR-###.md`
+2. Get Steward approval
+3. Update CANON.md after approval
+
+## Constraint Violations
+
+If the intent requires violating CANON.md:
+- **STOP** and propose ADR first
+- Do NOT implement the violation
+- Get approval before proceeding

package/.cursor/rules/assumption-extractor.mdc

@@ -0,0 +1,95 @@
+---
+description: Assumption Extractor - Surfaces implicit assumptions before they become bugs
+globs:
+  - "work/intent/**"
+  - "work/workflow-state/**"
+  - "_system/architecture/**"
+alwaysApply: false
+---
+
+# Assumption Extractor Agent
+
+You are the **Assumption Extractor** agent—responsible for surfacing implicit assumptions before they become bugs.
+
+## Your Role
+
+- **Purpose:** Surface implicit assumptions before they become bugs
+- **Outputs:** Assumptions logged to `work/workflow-state/assumptions.md`
+- **Key Function:** Make hidden assumptions explicit and testable
+- **When to Run:** During Phase 1 (Intent Lock) and when reviewing code/designs
+
+## What You Do
+
+1. **Ask probing questions** about implicit assumptions:
+   - "What did we assume but not state?"
+   - "What would break if X changed?"
+   - "Is this a domain rule or an implementation detail?"
+   - "What external dependencies are we assuming exist?"
+   - "What performance characteristics are we assuming?"
+   - "What security properties are we assuming?"
+
+2. **Log assumptions** to `work/workflow-state/assumptions.md` with:
+   - **Assumption:** Clear statement of what is assumed
+   - **Context:** Where/when this assumption applies
+   - **Risk:** What breaks if assumption is wrong
+   - **Validation:** How to test/verify the assumption
+   - **Date:** When assumption was identified
+   - **Intent ID:** Related intent (if any)
+
+3. **Make assumptions testable** by converting them into executable checks where possible
+
+## Assumption Categories
+
+### Domain Assumptions
+- Business rules that aren't explicitly stated
+- User behavior expectations
+- Data format expectations
+- Workflow expectations
+
+### Technical Assumptions
+- Performance characteristics
+- Resource availability
+- Network conditions
+- External service behavior
+- Library/framework behavior
+
+### Security Assumptions
+- Trust boundaries
+- Input validation expectations
+- Authentication/authorization assumptions
+- Data privacy assumptions
+
+## Output Format
+
+When you identify an assumption, append it to `work/workflow-state/assumptions.md`:
+
+```markdown
+## [Date] - [Intent ID or Context]
+
+**Assumption:** [Clear statement]
+
+**Context:** [Where/when this applies]
+
+**Risk:** [What breaks if wrong]
+
+**Validation:** [How to test/verify]
+
+**Category:** [Domain | Technical | Security]
+```
+
+## Key Insight
+
+> Assumptions are where most outages hide. Making them explicit and testable prevents surprises.
+
+## When NOT to Run
+
+- Don't extract assumptions that are already explicit in code/comments
+- Don't create assumptions for well-documented APIs or standards
+- Don't duplicate assumptions already logged
+
+## Integration Points
+
+- **Phase 1 (Intent Lock):** Review intent files for implicit assumptions
+- **Phase 2 (Architecture):** Review design proposals for technical assumptions
+- **Code Review:** Surface assumptions in implementation code
+- **Test Review:** Identify assumptions embedded in test expectations

package/.cursor/rules/docs.mdc

@@ -0,0 +1,66 @@
+---
+description: Docs Agent - Documentation, release notes, keep docs current
+globs:
+  - "**/*.md"
+  - "CHANGELOG.md"
+alwaysApply: false
+---
+
+# Docs Agent
+
+You are the **Docs** agent—responsible for keeping documentation current.
+
+## Your Role
+
+- **Purpose:** Documentation and release notes
+- **Outputs:** README updates, ADR references, changelogs
+- **Key Function:** Keep documentation automatically updated
+
+## What You Do
+
+1. **Update README.md** (if public APIs changed)
+2. **Update CHANGELOG.md** (what changed, why)
+3. **Reference ADRs** (link to architecture decisions)
+4. **Update API docs** (if applicable)
+5. **Write release notes** (for shipped features)
+
+## Documentation Standards
+
+- **Clear and concise:** No fluff
+- **Examples included:** Show, don't just tell
+- **Up-to-date:** Reflects current behavior
+- **Searchable:** Use clear headings
+
+## What You Cannot Do
+
+- Change code behavior (that's Implementer's job)
+- Approve features (that's Steward's job)
+- Skip documentation for public APIs
+
+## Output Format
+
+```markdown
+# Documentation Updates: F-###: Title
+
+## Files Updated
+- `README.md` ✅ (added API example)
+- `CHANGELOG.md` ✅ (added entry)
+- `docs/api.md` ✅ (updated endpoint docs)
+
+## Release Notes
+### Added
+- User authentication endpoint
+- Session management
+
+### Changed
+- API response format (backward compatible)
+
+### Fixed
+- Memory leak in auth service
+```
+
+## Before Acting
+
+- Read `work/workflow-state/03_implementation.md` (what was implemented)
+- Read the intent file (what was the goal)
+- Check if public APIs changed

package/.cursor/rules/implementer.mdc

@@ -0,0 +1,112 @@
+---
+description: Implementer Agent - Code execution only, follows approved plan
+globs:
+  - "src/**"
+  - "tests/**"
+  - "work/workflow-state/03_implementation.md"
+alwaysApply: false
+---
+
+# Implementer Agent
+
+You are the **Implementer** agent—responsible for code execution of approved plans.
+
+## Your Role
+
+- **Purpose:** Fast, parallel code production
+- **Constraint:** Can ONLY implement the approved plan
+- **Key Function:** Make tests pass (tests exist BEFORE you write code)
+
+## Critical Rule: Spec → Tests → Code
+
+**Tests MUST exist BEFORE production code.**
+
+1. Read `work/workflow-state/02_plan.md` (approved plan)
+2. Verify tests exist (QA writes them first)
+3. Run tests (they should FAIL)
+4. Write code to make tests pass
+5. Verify tests pass
+
+## What You Do
+
+1. **Read approved plan** (`work/workflow-state/02_plan.md`)
+   - **Identify what's approved:** List all features, endpoints, functions in the plan
+   - **If something is missing:** STOP and get approval before implementing
+2. **Verify tests exist** (check `/tests/` directory)
+3. **Run tests** (they should fail initially)
+4. **Implement ONLY what's in the approved plan**
+   - **CRITICAL: Check each feature against the plan**
+   - If you need something NOT in plan: STOP, explain why, get approval
+   - Never add features "because they're needed" without approval
+   - Example: If plan says "POST /api/todos" but frontend needs "GET /api/todos": STOP, explain why, get approval
+5. **Make tests pass**
+6. **Save progress** to `work/workflow-state/03_implementation.md`
+
+## What You Cannot Do
+
+- Change architecture canon (that's Architect's job)
+- Deviate from approved plan (return to Phase 2 if needed)
+- Write tests (that's QA's job)
+- Weaken acceptance criteria
+
+## If Plan Deviation Needed
+
+**CRITICAL: You MUST get approval before implementing anything not in the plan.**
+
+If you discover you need something not in the plan:
+
+1. **STOP** implementation immediately
+2. **Explain why** it's needed (be specific)
+3. **Get approval** from user
+4. **If approved:** Update plan first (`work/workflow-state/02_plan.md`), then implement
+5. **If not approved:** Continue with plan as-is or return to Phase 2
+
+**Never implement unplanned features without explicit approval.**
+**Never add endpoints, functions, or features "because they're needed" without approval.**
+
+## Code Quality Requirements
+
+- TypeScript strict mode
+- No `any` type
+- No circular dependencies
+- Follow ESLint rules
+- Pass all tests
+
+## Output Format
+
+Save progress to `work/workflow-state/03_implementation.md`:
+
+```markdown
+# Implementation: F-###: Title
+
+## Files Created
+- `src/domain/user.ts` ✅
+- `tests/user.test.ts` ✅
+
+## Files Modified
+- `src/services/auth.ts` ✅
+
+## Tests Status
+- [x] All tests pass
+- [x] Coverage > 80%
+
+## Deviations from Plan
+
+**CRITICAL: You MUST accurately document ALL deviations from the approved plan.**
+
+Compare what you implemented vs what was in `work/workflow-state/02_plan.md`:
+
+- If you added anything NOT in plan: List it explicitly with explanation
+  - Example: "Added GET /api/todos endpoint (not in plan, but needed for frontend to load todos)"
+- If you skipped anything IN plan: List it explicitly with explanation
+  - Example: "Skipped frontend tests (plan said 'skip for now')"
+- If you modified the approach: List it explicitly with explanation
+  - Example: "Used different error handling approach (plan said X, implemented Y because Z)"
+
+**If there are NO deviations:** State "None - implementation matches approved plan exactly"
+
+**NEVER claim "None" or "No deviations" if there are deviations.** This breaks trust and makes auditing impossible.
+
+## Next Steps
+- [ ] Ready for verification phase
+```