# Development Workflow Skills — Master Plan ## Context Ryan uses Claude Code as a general-purpose tool across many domains. His global config is lean and language-agnostic. He needs a set of skills that formalize his development workflow — from idea to deployment — so he can drive each step manually or let agents run autonomously when desired. This plan defines each process, its sub-processes, inputs/outputs, and the skills needed. Skills follow the existing `~/.claude/skills/` structure (SKILL.md + optional bundled resources). --- ## Process Overview ``` 1. Create Specs and Repo → PRD, Tech Design, ADRs, Patterns, Repo 2. Create Plan → Implementation Plan, Todo List, Status Files 3. Develop Code (TDD) → Working code (Red → Green → Refactor) 4. Bug Fixes → Targeted fix + test (standalone entry point) 5. CI/CD → Pipeline configs, deployment scripts ``` Cross-cutting reusable processes: - **Iterative Brainstorming** — used within Specs, Plans, and anywhere gaps need probing - **Refactor** — the "R" in TDD, invoked after tests pass - **Create/Update Docs** — invoked after any significant change --- ## Document Architecture ### Spec-Driven Development Documents Specs are static but updatable as the project evolves. Plans are living session outputs. Keep individual spec files focused and scannable — split when a file gets unwieldy rather than targeting a specific line count. #### Required Documents (per project) | Document | Location | Purpose | |----------|----------|---------| | **Spec Index** | `docs/specs/index.md` | Project overview, links to all specs | | **Architecture Spec** | `docs/specs/architecture.md` | High-level arch, tech stack, decisions | | **Module Specs** | `docs/specs/modules/<name>.md` | Per-module functional + technical spec | | **PRD** | `docs/prd.md` | Product requirements, goals, non-goals, user stories | | **ADRs** | `docs/adr/NNN-<decision>.md` | Individual architecture decision records | | **Competitive Analysis** | `docs/research/competitive-analysis.md` | Market landscape, competitor features | | **User Research** | `docs/research/user-research.md` | Simulated interviews, persona analysis | | **Success Metrics** | `docs/metrics/success-metrics.md` | KPIs, measurement plan, A/B test design | #### Working Memory Documents (living files) These are consumed by agents as context, so size discipline matters. Targets are flexible guidelines, not hard limits. | Document | Location | Purpose | Size Target | |----------|----------|---------|-------------| | **status.md** | `status.md` (project root) | Current phase, 3-5 active items, points to latest plan | ~30 lines | | **project_status.md** | `project_status.md` (project root) | Rolling project state, compacts past efforts | 100-200 lines | | **Plans** | `docs/plans/<feature-name>-plan.md` | Implementation plans from planning sessions | 100-300 lines | | **Idea Files** | `docs/ideas/<feature-name>-idea.md` | Raw brainstorm outputs | As needed | | **CLAUDE.md** | Project root | Agent working instructions, proven patterns | 50-150 lines | | **README.md** | Project root | Human onboarding | As needed | #### Feature-Scoped Documents (for large features on existing projects) Same structure, nested under `docs/features/<feature-name>/`: - `prd.md`, `specs/`, `adr/`, `research/`, `metrics/`, `plans/` --- ## Phase 1: Create Specs and Repo ### 1.1 Scoping → Skill: `/scope` **Purpose:** Take a raw idea and produce a complete PRD through structured conversation. **Process:** 1. User provides initial idea (text, voice dump transcript, or rough notes) 2. Skill uses reverse prompting — interviews the user with targeted questions and follow-ups 3. Iteratively refines until PRD sections are complete 4. Outputs structured PRD file **Inputs:** - Raw idea (text, transcript, or `<feature-name>-idea.md` from brainstorming) - Existing project context (if adding to existing project) **Outputs:** - `docs/prd.md` (or `docs/features/<name>/prd.md` for features) - Feeds into: Requirement Validation, Technical Planning **Skill Definition:** - Name: `scope` - Install level: **Global** (language-agnostic process) - Agent-invocable: No (requires user conversation) - Bundled resources: `references/prd-template.md` --- ### 1.2 Requirement Validation → Skill: `/validate-requirements` **Purpose:** Stress-test PRD requirements for feasibility, impact, and completeness. **Process:** 1. Read PRD and existing codebase (if applicable) 2. For each feature/requirement, validate: - Technical feasibility within current stack/codebase - User impact and value alignment - Completeness (no missing edge cases) 3. Run validation methods as appropriate: - **Market research**: Competitive landscape analysis - **Simulated user interviews**: AI personas representing target users - **Data-driven analysis**: If metrics/data available 4. Flag gaps, risks, contradictions 5. Output validation report and updated PRD **Inputs:** - PRD from scoping - Existing codebase (if applicable) **Outputs:** - `docs/research/competitive-analysis.md` - `docs/research/user-research.md` - Updated PRD with validation notes - Feeds into: Iterative Brainstorming, Technical Planning **Skill Definition:** - Name: `validate-requirements` - Install level: **Global** - Agent-invocable: Yes (can be chained after scoping) - Bundled resources: `references/validation-checklist.md`, `references/competitive-analysis-template.md`, `references/user-research-template.md` --- ### 1.3 Iterative Brainstorming → Skill: `/brainstorm` **Purpose:** Reusable process to probe, question, and fill gaps in any artifact. Always enforces a measurement/success lens. **Process:** 1. Accept target artifact (PRD, plan, spec, feature idea, blog post, etc.) 2. Run structured brainstorming: - **Gap analysis**: What's missing? What assumptions are untested? - **Reverse engineering**: "What problem is this actually solving?" - **Devil's advocate**: Challenge every major decision - **Measurement lens**: "How do we measure success for this?" — propose A/B tests, KPIs, instrumentation - **Open-ended probing**: "What questions should we be asking before implementing?" 3. Optionally call alternative model APIs (OpenAI, Google, etc.) for different perspectives — skill makes direct API calls using configured keys 4. Output structured findings and suggested changes **Inputs:** - Any artifact (PRD, plan, spec, idea dump, blog draft, etc.) - Context about what phase we're in **Outputs:** - Brainstorm findings with categorized gaps/suggestions - Updated artifact (if user approves changes) - `docs/metrics/success-metrics.md` (created or updated with measurement proposals) - Feeds into: Whatever process invoked it **Voice Dump Workflow (sub-process):** 1. User provides raw transcript (from Limitless Pendant or similar) 2. Skill restructures into coherent writing 3. Runs problem-space questions: "Reverse engineer the problem," "What open-ended questions should I ask?" 4. Outputs `docs/ideas/<feature-name>-idea.md` **Skill Definition:** - Name: `brainstorm` - Install level: **Global** (used across all project types and non-code contexts) - Agent-invocable: Yes (invoked by other skills during their flows) - Bundled resources: `references/brainstorm-framework.md`, `references/measurement-checklist.md` --- ### 1.4 Technical Planning → Skill: `/tech-plan` **Purpose:** Define tech stack, architecture, and technical specifications. **Process:** 1. Review PRD and validation outputs 2. Collaborate with user to determine: - Technical stack (framework, language, runtime) - UI component libraries (if applicable) - External services and dependencies - High-level cost analysis 3. Explore options before committing — always consider alternatives - For every major technical decision, present 2-3 concrete alternatives with tradeoffs - Classify constraints driving each choice: Hard (immutable), Soft (policy/choice), or Assumption (unvalidated) - Don't just identify problems with options — propose paths forward for each 4. Decompose PRD claims into testable statements - Break key requirements into atomic claims (e.g., "users need real-time updates" → is this validated? what latency actually matters?) - For each: is it stated with evidence, or assumed? Flag unsubstantiated claims as risks. 5. Consider scale implications 6. Pass architecture through review (optionally with alternative model) 7. Define branch naming conventions (e.g., `feature/some-feature`) 8. Create specification files **Inputs:** - PRD - Validation outputs (competitive analysis, user research) - Existing codebase context (if applicable) **Outputs:** - `docs/specs/architecture.md` - `docs/specs/index.md` - `docs/adr/001-<first-decision>.md` (and subsequent ADRs) - Feeds into: Pattern Creation, Create Plan **Skill Definition:** - Name: `tech-plan` - Install level: **Global** - Agent-invocable: Yes - Bundled resources: `references/architecture-spec-template.md`, `references/module-spec-template.md`, `references/adr-template.md`, `references/tech-stack-checklist.md` --- ### 1.5 Pattern Creation → Skill: `/establish-patterns` **Purpose:** Prove out key patterns with throwaway spike code, document what works, then discard the spikes. **Process:** 1. Review architecture spec and tech stack decisions 2. Identify critical patterns that need proving (API endpoints, data access, component structure, etc.) 3. Create minimal spike implementations for each pattern 4. Validate patterns work together 5. Document proven patterns into CLAUDE.md (code examples, conventions, gotchas) 6. Create/update module specs with pattern references 7. **Discard spike code** — patterns are captured in docs, real code is written cleanly during TDD **Inputs:** - Architecture spec - Tech stack decisions - ADRs **Outputs:** - Updated CLAUDE.md with proven patterns and code examples - `docs/specs/modules/<name>.md` for each module - Feeds into: Create Repo, Create Plan - Note: Spike code is deleted after patterns are documented **Skill Definition:** - Name: `establish-patterns` - Install level: **Project** (patterns are project-specific) - Agent-invocable: Yes - Bundled resources: `references/pattern-documentation-guide.md` --- ### 1.6 Create Repo and Environment → Skill: `/init-project` **Purpose:** Scaffold a new project from specs and patterns. **Process:** 1. Create directory structure based on architecture spec 2. Initialize git repo 3. Set up .gitignore (language-appropriate, always includes .env) 4. Install dependencies from tech stack decisions 5. Configure development environment 6. Create initial CLAUDE.md (invoke `write-claude-md` skill) 7. Create README.md with setup/build/run instructions 8. Create initial status.md and project_status.md 9. Set up docs/ directory structure with all spec files **Inputs:** - All spec documents (PRD, architecture, module specs, ADRs) - Proven patterns from pattern creation - Tech stack decisions **Outputs:** - Initialized git repo with full project structure - CLAUDE.md, README.md, .gitignore - status.md, project_status.md - docs/ directory with all specs - Feeds into: Create Plan (for first feature) **Skill Definition:** - Name: `init-project` - Install level: **Global** - Agent-invocable: No (user should review scaffolding) - Bundled resources: `references/project-structure-template.md`, `references/gitignore-templates/` --- ### 1.7 Create/Update Docs → Skill: `/update-docs` **Purpose:** Keep project documentation in sync with code changes. **Process:** 1. Scan for recent changes (git diff, modified files) 2. Identify which docs need updating (specs, CLAUDE.md, README, status files) 3. Propose updates 4. Apply approved changes 5. Compact project_status.md if it's getting long **Inputs:** - Recent code changes - Current doc state **Outputs:** - Updated documentation files - Feeds into: Next development cycle **Skill Definition:** - Name: `update-docs` - Install level: **Global** - Agent-invocable: Yes (can be triggered after commits) - Bundled resources: None (uses existing doc templates from project) --- ## Phase 2: Create Plan ### 2.1 Define Feature + Definition of Done → Skill: `/plan-feature` **Purpose:** Take a feature from the PRD and produce a complete implementation plan. **Process:** 1. Select feature from PRD 2. Define feature scope and acceptance criteria (Definition of Done) 3. Research codebase — look around, consider options, don't start coding yet 4. Run iterative brainstorming on the approach (invoke `/brainstorm`) 5. Create phased implementation plan (3-5 phases, 100-300 lines) 6. Generate todo list for each phase 7. Link plan to relevant specs 8. Update status.md to point to new plan **Inputs:** - PRD (specific feature) - Architecture spec and module specs - Current codebase state **Outputs:** - `docs/plans/<feature-name>-plan.md` - Updated status.md (points to latest plan) - Updated project_status.md - Feeds into: Develop Code **Skill Definition:** - Name: `plan-feature` - Install level: **Global** - Agent-invocable: No (user should own planning decisions) - Bundled resources: `references/plan-template.md`, `references/definition-of-done-template.md` --- ## Phase 3: Develop Code (TDD) ### 3.1 Branch + PR Setup → Skill: `/start-feature` **Purpose:** Create branch, worktree, and draft PR for a planned feature. **Process:** 1. Read the current plan from status.md 2. Create feature branch (`feature/<feature-name>`) 3. Optionally create worktree for isolation 4. Create draft PR with plan summary **Inputs:** - Implementation plan - Branch naming convention from tech-plan **Outputs:** - Feature branch - Draft PR (optional) - Feeds into: TDD cycle **Skill Definition:** - Name: `start-feature` - Install level: **Global** - Agent-invocable: No (user initiates feature work) --- ### 3.2 TDD Cycle → Skill: `/tdd` **Purpose:** Execute the Red-Green-Refactor cycle for a specific task from the plan. **Process:** 1. **Red**: Write failing tests based on the plan's current task 2. **Green**: Write minimum code to pass tests 3. **Refactor**: Step back, review against architecture spec and patterns in CLAUDE.md - Does the code fit the project's established patterns? - Is there duplication that should be extracted? - Are there architectural concerns beyond just passing tests? 4. Run full test suite to confirm nothing broke 5. Update status.md with progress **Inputs:** - Current plan task - Architecture spec and CLAUDE.md patterns - Existing test patterns in codebase **Outputs:** - Working, tested, refactored code - Updated status.md - Feeds into: Code Review **Skill Definition:** - Name: `tdd` - Install level: **Global** - Agent-invocable: Yes (can run through plan tasks autonomously) - Bundled resources: `references/refactor-checklist.md` --- ### 3.3 Code Review → Skill: `/review-code` **Purpose:** Multi-dimensional code review before committing. **Process:** 1. **Quality**: Code style, patterns, readability, maintainability 2. **Security**: OWASP top 10, dependency vulnerabilities, secrets exposure 3. **Performance**: Algorithmic complexity, unnecessary allocations, N+1 queries 4. Produce review report with findings categorized by severity 5. Suggest fixes for any issues found **Inputs:** - Changed files (git diff) - Architecture spec and CLAUDE.md patterns **Outputs:** - Review report - Suggested fixes - Feeds into: Fix issues → Commit Code **Skill Definition:** - Name: `review-code` - Install level: **Global** - Agent-invocable: Yes (can be chained after TDD) - Bundled resources: `references/review-checklist.md`, `references/security-checklist.md` --- ### 3.4 Commit Code → (uses existing git workflow) Not a separate skill — follows Ryan's existing git rules (never commit without permission, never amend without permission). The TDD and review skills prepare the code; Ryan commits manually. --- ## Phase 4: Bug Fixes ### 4.1 Fix Issue → Skill: `/fix-bug` **Purpose:** Standalone entry point for bug fixes outside the feature development flow. **Process:** 1. Accept bug description (or GitHub issue reference) 2. Investigate root cause in codebase 3. Write failing test that reproduces the bug 4. Fix the bug (minimum change) 5. Run test suite 6. Refactor if needed 7. Prepare for review **Inputs:** - Bug description or issue reference - Current codebase **Outputs:** - Fix + regression test - Feeds into: Code Review → Commit **Skill Definition:** - Name: `fix-bug` - Install level: **Global** - Agent-invocable: No (user should validate bug understanding) - Bundled resources: `references/bug-fix-template.md` --- ## Phase 5: CI/CD ### 5.1 CI/CD Pipeline Development → Skill: `/setup-cicd` **Purpose:** Help develop and maintain CI/CD pipeline configurations. **Process:** 1. Review tech stack and deployment requirements 2. Generate pipeline config (GitHub Actions, etc.) covering: - Security review (dependency scanning, secret detection) - Test execution - Build process - Deployment configuration - Monitoring setup 3. Create/update pipeline files 4. Document pipeline in README **Inputs:** - Tech stack decisions - Architecture spec - Deployment requirements **Outputs:** - `.github/workflows/` or equivalent pipeline configs - Updated README with CI/CD documentation - Feeds into: Ongoing development **Skill Definition:** - Name: `setup-cicd` - Install level: **Global** - Agent-invocable: No (infrastructure changes need user review) - Bundled resources: `references/cicd-templates/` (GitHub Actions, etc.) --- ## Skill Summary | # | Skill | Slash Command | Install Level | Agent-Invocable | Phase | |---|-------|--------------|---------------|-----------------|-------| | 1 | scope | `/scope` | Global | No | Specs | | 2 | validate-requirements | `/validate-requirements` | Global | Yes | Specs | | 3 | brainstorm | `/brainstorm` | Global | Yes | Cross-cutting | | 4 | tech-plan | `/tech-plan` | Global | Yes | Specs | | 5 | establish-patterns | `/establish-patterns` | Project | Yes | Specs | | 6 | init-project | `/init-project` | Global | No | Specs | | 7 | update-docs | `/update-docs` | Global | Yes | Cross-cutting | | 8 | plan-feature | `/plan-feature` | Global | No | Plan | | 9 | start-feature | `/start-feature` | Global | No | Develop | | 10 | tdd | `/tdd` | Global | Yes | Develop | | 11 | review-code | `/review-code` | Global | Yes | Develop | | 12 | fix-bug | `/fix-bug` | Global | No | Bug Fixes | | 13 | setup-cicd | `/setup-cicd` | Global | No | CI/CD | --- ## Process Flow with Inputs/Outputs ``` IDEA (raw text / voice dump / transcript) │ ▼ /scope ──────────────────────► PRD │ │ ▼ ▼ /validate-requirements ──────► Competitive Analysis, User Research, Updated PRD │ │ ▼ ▼ /brainstorm (reusable) ──────► Gap findings, Success Metrics │ │ ▼ ▼ /tech-plan ──────────────────► Architecture Spec, Spec Index, ADRs │ │ ▼ ▼ /establish-patterns ─────────► Working patterns, Updated CLAUDE.md, Module Specs │ │ ▼ ▼ /init-project ───────────────► Scaffolded repo, all docs, status files │ ▼ /plan-feature ───────────────► Implementation Plan, Updated Status │ ▼ /start-feature ──────────────► Feature branch, Draft PR │ ▼ /tdd (loop) ─────────────────► Working tested code │ ▼ /review-code ────────────────► Review report, fixes │ ▼ [User commits] │ ▼ /setup-cicd ─────────────────► Pipeline configs Bug path: Issue → /fix-bug → /review-code → [User commits] ``` --- ## Resolved Decisions 1. **ADRs**: Individual files (`docs/adr/NNN-<decision>.md`) — standard practice 2. **Pattern creation**: Throwaway spikes — document patterns, discard spike code, write real code during TDD 3. **Doc locations**: `docs/` directory structure as proposed above 4. **Feature-scoped docs**: `docs/features/<feature-name>/` mirroring top-level structure 5. **Templates**: Reference markdown files in skill bundles that guide conversation and structure output 6. **`/dev-docs`**: Alias for `/scope` — not a separate skill 7. **"Second brain"**: The entire `docs/` portfolio — specs, plans, status files, research — acts as persistent project memory for agents 8. **Alternative model integration**: Direct API calls from within skills (requires API keys configured) --- ## Progress ### `/brainstorm` — COMPLETE (iteration 1) **Status:** Built, eval'd, and refined. Ready for real-world use. May iterate further after other skills exercise it. **Files delivered:** ``` ~/.claude/skills/brainstorm/ ├── SKILL.md (169 lines) ├── references/ │ ├── brainstorm-framework.md (170 lines — 5 dimensions + constraint classification) │ └── measurement-checklist.md (126 lines — metrics by artifact type + anti-patterns) ├── scripts/ │ └── alt_perspective.py (calls OpenAI GPT-4o via uv run --with openai) └── evals/ └── evals.json (3 test cases, 5 assertions each) ``` **Eval results (iteration 1):** | Config | Pass Rate | Avg Time | Avg Tokens | |--------|-----------|----------|------------| | With skill | 100% (15/15) | 192.6s | 25,675 | | Without skill (baseline) | 80% (12/15) | 115.1s | 16,091 | | **Delta** | **+20%** | **+77.5s** | **+9,584** | Key discriminators: - "Proposes success metrics or measurement plan" — passes 3/3 with-skill, fails 2/3 without - "Challenges WebSocket choice or asks why not SSE/polling" — passes with-skill, fails without - Eval 3 passes both configs but with-skill output is measurably richer (5 concrete metrics vs "you need metrics") **Post-eval refinement:** - Added **constraint classification** (Hard/Soft/Assumption) to Devil's Advocate dimension, informed by comparison with Miessler's FirstPrinciples skill and obra's brainstorming skill **Decisions made during build:** - `uv run --with openai` for Python dependency management (no venv pollution across projects) - macOS Keychain for OPENAI_API_KEY storage (`security find-generic-password` in .zshrc) - Alt-model perspective is optional — graceful degrade if no API key **Eval workspace:** `~/.claude/skills/brainstorm-workspace/iteration-1/` --- ### `/scope` — COMPLETE (iteration 1) **Status:** Built, no evals yet. Ready for real-world use and iteration. **Files delivered:** ``` ~/.claude/skills/scope/ ├── SKILL.md (~170 lines) └── references/ └── prd-template.md (~160 lines — 11-section PRD structure) ``` **Design decisions:** - Interactive only (no autonomous mode) — PRD scoping requires user conversation - Reverse-prompting interview flow: one question at a time, not a questionnaire - Five interview phases: Problem Space → Solution Shape → Requirements → Constraints/Measurement → Boundaries - Handles three input modes: raw text, file path (idea files/transcripts), or ambient context - Voice dump support: restructures transcripts before interviewing - Existing PRD detection: asks whether to revise, expand with feature, or start fresh - Output follows standardized template with constraint classification (Hard/Soft/Assumption) - Downstream skills (`/validate-requirements`, `/tech-plan`, `/plan-feature`) consume the PRD output --- ### `/validate-requirements` — COMPLETE (iteration 1) **Status:** Built, no evals yet. Ready for real-world use and iteration. **Files delivered:** ``` ~/.claude/skills/validate-requirements/ ├── SKILL.md (~170 lines) └── references/ ├── validation-checklist.md (~150 lines — 4-dimension evaluation framework) ├── competitive-analysis-template.md (~100 lines — WebSearch-based market research output) └── user-research-template.md (~120 lines — simulated persona interview output) ``` **Design decisions:** - Agent-invocable (can be chained after `/scope` in autonomous mode) - Same mode detection pattern as brainstorm (interactive vs. autonomous based on invocation context) - WebSearch for competitive analysis — real web data, not hallucinated market info - Simulated user interviews — AI role-plays PRD personas. Clearly labeled as simulated, not real research - PRD updates use inline `> **Validation Note:** ...` callouts — preserves user's original text while flagging issues - No alt-model integration (unlike brainstorm) — competitive analysis via WebSearch provides external grounding instead - Validation checklist uses 4 dimensions: Technical Feasibility, Completeness, Impact Alignment, Consistency - Cross-cutting analysis covers: constraint audit, metrics review, priority balance, dependency mapping, gap scan - Severity classification matches brainstorm: Critical / Important / Minor --- ### `/tech-plan` — COMPLETE (iteration 1) **Status:** Built, no evals yet. Ready for real-world use and iteration. **Files delivered:** ``` ~/.claude/skills/tech-plan/ ├── SKILL.md (~305 lines) └── references/ ├── architecture-spec-template.md (~258 lines — 11-section spec structure) ├── adr-template.md (~120 lines — decision record with constraint classification) ├── module-spec-template.md (~152 lines — per-module functional + interface spec) └── tech-stack-checklist.md (~161 lines — 6-dimension evaluation framework) ``` **Design decisions:** - Agent-invocable (can be chained after `/validate-requirements` in autonomous mode) - Same mode detection pattern as brainstorm/validate-requirements (interactive vs. autonomous) - **Claim decomposition** (Step 3): Breaks PRD requirements into atomic technical claims classified as Evidenced/Assumed/Implied. Architecture-driving claims get the most scrutiny. This is the unique differentiator — forces explicit reasoning about what's actually validated vs. assumed before making stack choices. - **Alternative proposals** (Step 4): Every major decision gets 2-3 options with tradeoffs. Driving constraint classified as Hard/Soft/Assumption. User decides in interactive mode; autonomous mode picks best-fit and flags low-confidence choices. - WebSearch for real data when novel comparison criteria exist (benchmarks, pricing, library status) - No alt-model integration (like validate-requirements) — the structured comparison process provides sufficient rigor - Conventions defined in Step 7 feed directly into CLAUDE.md via `/init-project` and guide `/establish-patterns` - ADR quality checklist prevents straw-man comparisons and "no significant risks" cop-outs - Architecture spec template includes claim traceability table (Section 10) connecting decisions back to PRD requirements - Module specs bridge architecture (system-level) to implementation plans (task-level) --- ### `/establish-patterns` — COMPLETE (iteration 1) **Status:** Built as a reusable project-bootstrapping prompt. Not a global skill — each project gets its own copy generated from the prompt. **Files delivered:** ``` ~/Documents/ryan-lynch-brain/Professional Development/Miscellaneous/Productivity/ System Prompts/Project-specific Prompts/ └── establish-patterns-skill-prompt.md (~200 lines — full spec for generating the skill) ``` **Design decisions:** - **Not a global skill** — patterns are inherently project-specific. Instead: a reusable prompt stored in the brain vault that generates `.claude/skills/establish-patterns/` in any project. - Spike code lives in `_spikes/` directory (gitignored), deleted after patterns are documented - Patterns documented as concrete, copy-pasteable code examples in CLAUDE.md (20-40 lines each) - Module specs updated with implementation considerations discovered during spiking - Same interactive/autonomous mode convention as global skills - Pattern categories: data access, API, component, integration, cross-cutting - Risk-based prioritization: high-risk (architecture-dependent) patterns spiked first - Integration validation step: verify key patterns work together, not just in isolation - Anti-patterns guide prevents common mistakes (production code in spikes, untested spikes, happy-path-only docs) --- ### `/init-project` — COMPLETE (iteration 1) **Status:** Built, no evals yet. Ready for real-world use and iteration. **Files delivered:** ``` ~/.claude/skills/init-project/ ├── SKILL.md (~362 lines) └── references/ ├── project-structure-template.md (~225 lines — layouts for JS/TS, Python, Rust, Go) └── gitignore-templates.md (~185 lines — language-specific patterns) ``` **Design decisions:** - **Not agent-invocable** — scaffolding always needs user review (directory locations, GitHub repo creation, dependency installation) - **No mode detection** — always interactive. This is the only skill in the chain that doesn't have autonomous mode, because scaffolding decisions are inherently user-facing - **Invokes `write-claude-md` skill** via Skill tool for CLAUDE.md generation rather than duplicating its logic — respects single-responsibility - **GitHub integration** via `gh repo create` — private by default, SSH remote per global config (`RyanLynchUF`) - **Spec document handling**: copies existing specs into `docs/` structure, creates placeholder files pointing to upstream skills when specs are missing - **Status file bootstrapping**: creates both `status.md` (~30 lines, agent working memory) and `project_status.md` (100-200 lines, rolling state) with content derived from PRD milestones - `.env.example` created only when architecture spec or PRD mentions environment variables — no empty placeholders - Gitignore templates cover JS/TS, Python, Rust, Go with a universal section (`.env`, OS files, IDE dirs) that's always included - Project structure templates are fallback defaults — architecture spec conventions (Section 9) override them when available - Explicitly does NOT commit or push — user decides when to make the initial commit --- ### `/update-docs` — COMPLETE (iteration 1) **Status:** Built, no evals yet. Ready for real-world use and iteration. **Files delivered:** ``` ~/.claude/skills/update-docs/ └── SKILL.md (~244 lines) ``` **Design decisions:** - **No bundled resources** — as specified in the plan. This skill consumes existing project docs and templates rather than defining new ones - **Agent-invocable** with interactive/autonomous dual mode (standard pattern). Autonomous mode focuses on status files and CLAUDE.md; skips README unless structural changes detected - **Reactive, not generative** — unlike other skills in the chain that create artifacts from scratch, this one responds to what changed. git diff drives the analysis, not a template - **Change categorization table** maps code change types to affected docs — prevents both over-updating (touching docs for irrelevant changes) and under-updating (missing docs that should change) - **project_status.md compaction** built in: entries older than 2 weeks get grouped by milestone, resolved issues archived. Keeps the file within 100-200 line target as projects age - **CLAUDE.md updates** apply the `write-claude-md` pruning test and enforce the 150-line limit. Suggests `.claude/rules/` migration when approaching the cap - **Spec updates are judgment-gated** — in interactive mode, explains reasoning before editing specs. In autonomous mode, applies clear-cut updates and flags judgment calls for review - **Scope argument** (`all`, `status`, `readme`, `specs`, or file path) lets users target specific doc categories without running the full scan --- ### `/plan-feature` — COMPLETE (iteration 1) **Status:** Built, no evals yet. Ready for real-world use and iteration. **Files delivered:** ``` ~/.claude/skills/plan-feature/ ├── SKILL.md (~210 lines) └── references/ ├── plan-template.md (~130 lines — phased plan structure with task/test/spec-ref format) └── definition-of-done-template.md (~130 lines — 5-category DoD framework with phase splitting) ``` **Design decisions:** - **Interactive only** — no autonomous mode. Planning requires user trade-off decisions about scope, phasing, and priorities. This is the only Phase 2 skill, and it's where the user commits to what gets built and in what order. - **Codebase research step** (Step 1c) — scans existing code before planning. For greenfield projects this is light; for existing codebases it identifies patterns, test conventions, and relevant code the feature will interact with. - **Optional brainstorm invocation** (Step 4b) — asks the user before invoking `/brainstorm` on the approach. For simple features it's overhead; for complex ones it catches gaps before they become phase 3 surprises. - **Phase design principles** enforce independently-testable phases — no half-built state between phases. Each phase has its own DoD (subset of feature-level DoD). - **Task granularity** targets TDD cycles — each task names the behavior and key test cases. The `/tdd` skill expands these into actual test code. - **Spec cross-references** on every task (PRD requirement ID, ADR, module spec, or CLAUDE.md pattern) — creates traceability from plan back to specs and helps `/tdd` understand *why* something is being built. - **Risk table and open questions** with phase-blocking annotations — `/tdd` can proceed with unblocked phases while questions about later phases are resolved. - **Status file updates** (Step 7) — updates both `status.md` and `project_status.md` to reflect the new plan, keeping agent working memory current. --- ### `/start-feature` — COMPLETE (iteration 1) **Status:** Built, no evals needed (procedural skill — branches, PRs, status updates). Ready for real-world use and iteration. **Files delivered:** ``` ~/.claude/skills/start-feature/ └── SKILL.md (~175 lines) ``` **Design decisions:** - **Interactive only** — no autonomous mode. Branch creation and PR creation affect shared state (remote repo). User confirms every externally-visible action. - **No bundled resources** — this skill is procedural (git commands, `gh` CLI), not template-driven. The plan file from `/plan-feature` provides all the content. - **Plan-driven setup** — reads feature metadata (name, phases, DoD, scope) from the plan file rather than asking the user to re-specify. Follows the `status.md` pointer that `/plan-feature` sets. - **Branch naming convention cascade**: CLAUDE.md → architecture spec conventions → default `feature/<name>`. Respects project-specific conventions established by `/tech-plan`. - **Conflict detection** before branch creation — checks both local and remote for existing branches. Presents options rather than silently failing or overwriting. - **Empty commit for draft PRs** — `git commit --allow-empty` so the branch can be pushed and a draft PR created before any code exists. PR body includes phase checklist from the plan. - **EnterWorktree tool** (not raw git worktree commands) for worktree creation — uses Claude Code's built-in worktree management with automatic cleanup. - **Minimal tool set** — no Write tool (edits status files via Edit), no WebSearch (no external data needed), no Skill tool (doesn't chain to other skills). --- ### `/tdd` — COMPLETE (iteration 1) **Status:** Built, no evals yet. Ready for real-world use and iteration. **Files delivered:** ``` ~/.claude/skills/tdd/ ├── SKILL.md (~210 lines) └── references/ ├── refactor-checklist.md (~140 lines — 7-area checklist + severity guide) └── testing-anti-patterns.md (~150 lines — 5 anti-patterns with gate functions) ``` **Design decisions:** - **Agent-invocable** with interactive/autonomous dual mode (standard pattern). Autonomous mode loops through all tasks in the current phase; interactive mode executes one task at a time with user confirmation between cycles. - **Plan-driven execution** — reads the plan file via `status.md` pointer (set by `/plan-feature`). Task IDs from the plan (e.g., `1.2`, `2.3`) are the primary navigation mechanism. Can also accept a phase number or file path as `$ARGUMENTS`. - **Test runner auto-detection** — scans for `package.json` scripts, `pytest.ini`, `Makefile`, `Cargo.toml`, etc. to determine how the project runs tests. Falls back to common commands in autonomous mode; asks in interactive mode. - **Strict Red-Green-Refactor discipline**: Red verifies tests fail for the *right* reasons (missing implementation, not broken test infra). Green writes minimum code only. Refactor uses the bundled checklist and checks against CLAUDE.md patterns. - **No Skill tool** — unlike `/plan-feature` which delegates to `/brainstorm`, the TDD skill is self-contained. It reads specs but doesn't invoke other skills mid-cycle. This keeps the feedback loop tight. - **No WebSearch** — implementation work is code-focused. If external research is needed, the plan should have covered it. - **Status file updates after each task** — both `status.md` and `project_status.md` get incremental updates so progress survives session boundaries. Uses Edit for targeted changes. - **Phase boundary checkpoints** — in interactive mode, completing a phase triggers a DoD check and suggests `/review-code` before continuing. In autonomous mode, phase completion is a natural stopping point. - **Refactor checklist** is ordered by impact (pattern conformance → duplication → complexity → names → test quality → interface → performance). Includes anti-patterns for each area to prevent over-refactoring. --- ### `/review-code` — COMPLETE (iteration 1) **Status:** Built, no evals yet. Ready for real-world use and iteration. **Files delivered:** ``` ~/.claude/skills/review-code/ ├── SKILL.md (~376 lines) └── references/ ├── review-checklist.md (~130 lines — 8-area quality framework, language-agnostic) ├── security-checklist.md (~174 lines — universal OWASP Top 10 checks) └── stacks/ ├── javascript-typescript.md (~114 lines — JS/TS quality + security + performance) ├── python.md (~133 lines — Python quality + security + performance) ├── go.md (~135 lines — Go quality + security + performance) └── rust.md (~144 lines — Rust quality + security + performance) ``` **Design decisions:** - **Hybrid global/project approach** — Process is global (SKILL.md), stack-specific knowledge is in separate files loaded via progressive disclosure. A Python project never sees JS security checks. - **Stack detection** (Step 3b): Detects language from project markers (package.json, pyproject.toml, Cargo.toml, go.mod) and loads only the matching `references/stacks/` file. Multi-language projects load multiple stack files but apply each only to its own files in the diff. - **Project-local override**: If a project has `.claude/skills/review-code/references/`, those files take precedence over global stack references. This lets `/init-project` or `/establish-patterns` generate project-tuned checklists (e.g., "Next.js + Prisma + NextAuth" instead of generic JS/TS). - **Agent-invocable** with interactive/autonomous dual mode (standard pattern). Autonomous mode produces full report; critical findings block commit. - **Three review dimensions**: Quality (pattern conformance, readability, test quality, interfaces), Security (OWASP categories, stack-specific dangerous functions), Performance (algorithmic, resource, concurrency). - **Fix application workflow** (interactive mode): Offers to apply fixes for critical findings, walks through important ones, skips minor unless asked. - **No WebSearch or Skill tool** — review is code-focused. External research should have happened during planning. - **Universal checklists are language-agnostic** — removed all language-specific examples from review-checklist.md and security-checklist.md. JS-leaning examples (JSDoc, promise chains, etc.) replaced with generic equivalents. - **Pre-flight checks** (after Step 2): Skip review for trivially correct changes (docs-only, version bumps, generated files, draft PRs). Avoids wasting time on changes that don't need code review. - **Do Not Flag list** (before review dimensions): Explicit false-positive exclusion list — pre-existing issues, linter territory, pedantic nitpicks, suppressed warnings, hypothetical issues, style preferences. Inspired by Anthropic's official code-review plugin. - **Validation pass** (Step 8): Re-examines each Critical/Important finding against actual surrounding code before reporting. Checks whether context resolves the concern, verifies the issue is introduced by the diff, and confirms suggestions are actionable. Expected to filter 20-50% of initial findings. Inspired by Anthropic's multi-agent validation approach, adapted to single-skill execution. --- ### `/fix-bug` — COMPLETE (iteration 1) **Status:** Built, no evals yet. Ready for real-world use and iteration. **Files delivered:** ``` ~/.claude/skills/fix-bug/ ├── SKILL.md (~258 lines) └── references/ └── bug-fix-template.md (~37 lines — structured output format) ``` **Design decisions:** - **Interactive only** — no autonomous mode. Wrong diagnosis leads to wrong fixes, so the user must confirm the root cause hypothesis before any code changes. This is the key gate that prevents cascading bad fixes. - **Not agent-invocable** — sits outside the normal feature development flow. Can be entered from anywhere — no plan or feature branch required. - **Investigation-first TDD**: Prepends a systematic investigation step (Steps 1-2) before the standard Red-Green-Refactor cycle (Steps 3-5). The investigation traces from symptom → code path → hypothesis → user confirmation. - **GitHub issue integration** — accepts issue URLs/numbers via `gh issue view`, extracting title, body, labels, and reproduction steps. Also accepts file paths, text descriptions, or no-argument interactive mode. - **Reuses TDD references** — reads `/tdd/references/testing-anti-patterns.md` and `/tdd/references/refactor-checklist.md` rather than duplicating that content. Single source of truth for test quality and refactor guidance. - **Minimum-change discipline** — Step 4 explicitly prohibits refactoring adjacent code, adding features, or "while I'm here" changes. Fix the root cause, nothing more. - **Regression-aware** — if the fix causes other tests to fail, presents the situation to the user (existing tests may rely on buggy behavior) rather than silently adjusting. - **Chains to `/review-code`** via suggestion in output, not by invoking it. User decides whether to review before committing. --- ### Remaining Skills | # | Skill | Status | |---|-------|--------| | 1 | `/init-project` | **COMPLETE** (iteration 1) | | 5 | `/update-docs` | **COMPLETE** (iteration 1) | | 6 | `/plan-feature` | **COMPLETE** (iteration 1) | | 7 | `/start-feature` | **COMPLETE** (iteration 1) | | 8 | `/tdd` | **COMPLETE** (iteration 1) | | 9 | `/review-code` | **COMPLETE** (iteration 1) | | 10 | `/fix-bug` | **COMPLETE** (iteration 1) | | 11 | `/setup-cicd` | **COMPLETE** (iteration 1) | --- ## Resolved Decisions (addendum) 9. **Python dependency management**: `uv run --with <package>` for ephemeral environments — no venv pollution across projects 10. **API key storage**: macOS Keychain + .zshrc export — not Claude Code's settings.json (plaintext, not secure for secrets) 11. **Constraint classification**: Added to brainstorm Devil's Advocate dimension after comparing with Miessler FirstPrinciples and obra brainstorming skills 12. **Alternative proposals / claim decomposition**: Folded into `/tech-plan` process (steps 3-4) rather than brainstorm — tech-plan makes decisions, brainstorm analyzes 13. **`/establish-patterns` install level**: Changed from project-level skill to reusable bootstrapping prompt stored in brain vault. Avoids chicken-and-egg problem (skill runs before project exists) and keeps global skills directory clean. Each project gets its own copy generated from the prompt. --- ## ORIGINAL BUILD PLAN: `/brainstorm` Skill (archived — build complete) <details> <summary>Click to expand original build plan</summary> ### Context This is the first skill to build because it's foundational — other skills (`/scope`, `/validate-requirements`, `/tech-plan`, `/plan-feature`) will invoke it. It's a reusable process for stress-testing any artifact by probing for gaps, challenging assumptions, and enforcing a measurement mindset. ### Final Skill Spec - **Name**: `brainstorm` - **Install level**: Global (`~/.claude/skills/brainstorm/`) - **Agent-invocable**: Yes - **Degree of freedom**: High (brainstorming is inherently variable) - **Input**: File path argument (`/brainstorm docs/prd.md`), inline pasted text, or ambient context from current conversation - **Alt model**: OpenAI API (GPT-4o) for alternative perspectives - **Voice dumps**: Excluded from v1 - **Output mode**: - **User-invoked**: Interactive Q&A — ask probing questions one at a time, build understanding iteratively, produce summary at end - **Agent-invoked**: Autonomous — analyze artifact, produce structured findings, return to calling skill without user interaction ### File Structure ``` ~/.claude/skills/brainstorm/ ├── SKILL.md # Core skill definition (~150-200 lines) ├── references/ │ ├── brainstorm-framework.md # The 5 brainstorming dimensions with examples │ └── measurement-checklist.md # Success metrics patterns by artifact type └── scripts/ └── alt_perspective.py # Calls OpenAI API for alternative viewpoint ``` ### Test Cases 1. **PRD gap analysis**: Point at a sample PRD with intentional gaps (missing non-functional requirements, no success metrics) — verify the skill identifies them 2. **Plan stress test**: Give it an implementation plan and check it challenges assumptions and asks about measurement 3. **Agent-invoked mode**: Simulate another skill calling brainstorm and verify it produces autonomous findings without interactive pauses </details> ### Remaining Implementation Order (after brainstorm) `/validate-requirements` → `/tech-plan` → `/establish-patterns` → `/init-project` → `/update-docs` → `/plan-feature` → `/start-feature` → `/tdd` → `/review-code` → `/fix-bug` → `/setup-cicd`