@zigrivers/scaffold 3.0.2 → 3.1.0

package/README.md

@@ -1,12 +1,12 @@
 # Scaffold
 
-A TypeScript CLI that assembles AI-powered prompts at runtime to guide you from "I have an idea" to working software. Scaffold walks you through 60 structured pipeline steps — organized into 16 phases — plus 10 utility tools, and Claude Code handles the research, planning, and implementation for you.
+A TypeScript CLI that assembles AI-powered prompts at runtime to guide you from "I have an idea" to working software. Scaffold walks you through 60 structured pipeline steps — organized into 16 phases — plus 10 utility tools, and the supported AI tools handle the research, planning, and implementation for you.
 
 By the end, you'll have a fully planned, standards-documented, implementation-ready project with working code.
 
 ## What is Scaffold?
 
-Scaffold is a composable meta-prompt pipeline built for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Anthropic's command-line coding tool. If you have an idea for a software project but don't know where to start — or you want to make sure your project is set up with solid architecture, standards, and tests from day one — Scaffold guides you through every step.
+Scaffold is a composable meta-prompt pipeline built for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Gemini, and other supported AI coding tools. If you have an idea for a software project but don't know where to start — or you want to make sure your project is set up with solid architecture, standards, and tests from day one — Scaffold guides you through every step.
 
 Here's how it works:
 
@@ -19,9 +19,9 @@ Here's how it works:
 You can run steps two ways:
 
 - **CLI**: `scaffold run create-prd` — the assembly engine builds a full prompt from the meta-prompt, knowledge base entries, and project context. Best for the structured pipeline with dependency tracking.
-- **Slash commands**: `/scaffold:create-prd` in Claude Code — uses pre-rendered, self-contained prompts. Best for quick access to individual commands without the full pipeline ceremony.
+- **Slash commands**: `/scaffold:create-prd` in Claude Code or Gemini — uses pre-rendered, self-contained prompts. Best for quick access to individual commands without the full pipeline ceremony.
 
-Either way, Scaffold constructs the prompt and Claude does the work. The CLI tracks pipeline state and dependencies; slash commands are fire-and-forget.
+Either way, Scaffold constructs the prompt and the target AI tool does the work. The CLI tracks pipeline state and dependencies; slash commands are fire-and-forget.
 
 ## Key Concepts
 
@@ -118,7 +118,7 @@ Install the Scaffold plugin inside Claude Code for slash commands AND the intera
 This gives you:
 - **Slash commands** (`/scaffold:create-prd`, `/scaffold:tdd`, etc.) — quick access to any pipeline step
 - **Scaffold Runner skill** — intelligent interactive wrapper that surfaces decision points (depth level, strictness, optional sections) before execution instead of letting Claude pick defaults silently
-- **Pipeline reference skill** — shows pipeline ordering, dependencies, and completion status
+- **Pipeline reference skill** — shows pipeline ordering, dependencies, and phase structure
 - **Multi-model dispatch skill** — correct invocation patterns for Codex and Gemini CLIs
 
 **Usage** — just tell Claude Code what you want in natural language:
@@ -138,7 +138,9 @@ The plugin is optional — everything it does can also be done with `scaffold ru
 > ```bash
 > scaffold skill install
 > ```
-> This copies the Scaffold Runner, Pipeline Reference, and Multi-Model Dispatch skills to `.claude/skills/` in your project.
+> This copies the Scaffold Runner and Pipeline Reference skills to both `.claude/skills/` and `.agents/skills/` in your project.
+
+> **Gemini users**: `scaffold build` keeps a root `GEMINI.md` in sync with the shared runner instructions and generates `.gemini/commands/scaffold/*.toml` slash commands. Plain prompts like `scaffold status` work because Gemini loads `GEMINI.md`.
 
 ## Updating
 
@@ -833,12 +835,12 @@ src/
 ├── cli/middleware/    # Project root detection, output mode resolution
 ├── cli/output/       # Output strategies (interactive, json, auto)
 ├── core/assembly/    # Assembly engine — meta-prompt → full prompt
-├── core/adapters/    # Platform adapters (Claude Code, Codex, Universal)
+├── core/adapters/    # Platform adapters (Claude Code, Gemini, Codex, Universal)
 ├── core/dependency/  # DAG builder, topological sort, eligibility
 ├── core/knowledge/   # Knowledge update assembler
 ├── state/            # State manager, lock manager, decision logger
 ├── config/           # Config loading, migration, schema validation
-├── project/          # Project detector, CLAUDE.md manager, adoption
+├── project/          # Project detector, CLAUDE.md/GEMINI.md managers, adoption
 ├── wizard/           # Init wizard (interactive + --auto)
 ├── validation/       # Config, state, frontmatter validators
 ├── types/            # TypeScript types and enums
@@ -851,7 +853,7 @@ src/
 - **Assembly engine** (`src/core/assembly/engine.ts`) — Pure orchestrator with no I/O. Constructs 7-section prompts from meta-prompt + knowledge + context + methodology + instructions + depth guidance.
 - **State manager** (`src/state/state-manager.ts`) — Atomic writes via tmp + `fs.renameSync()`. Tracks step status, in-progress records, and next-eligible cache. Includes migration system for step renames and retired steps.
 - **Dependency graph** (`src/core/dependency/`) — Kahn's algorithm topological sort with phase-aware ordering and cycle detection.
-- **Platform adapters** (`src/core/adapters/`) — 3-step lifecycle (initialize → generateStepWrapper → finalize) producing hidden adapter artifacts under `.scaffold/generated/claude-code/`, `.scaffold/generated/codex/`, and `.scaffold/generated/universal/`.
+- **Platform adapters** (`src/core/adapters/`) — 3-step lifecycle (initialize → generateStepWrapper → finalize) producing `.scaffold/generated/claude-code/commands/`, `.scaffold/generated/codex/AGENTS.md`, `.scaffold/generated/universal/prompts/README.md`, and Gemini project-local files under `.agents/skills/`, `GEMINI.md`, and `.gemini/commands/scaffold/`.
 - **Project detector** (`src/project/detector.ts`) — Scans for file system signals to classify projects as greenfield, brownfield, or v1-migration.
 - **Check command** (`src/cli/commands/check.ts`) — Applicability detection for conditional steps (platform detection, GitHub remote detection, CLI availability).
 
@@ -864,6 +866,7 @@ knowledge/            # 61 domain expertise entries (core, product, review, vali
 methodology/          # 3 YAML presets (deep, mvp, custom)
 commands/             # 72 Claude Code slash commands (60 pipeline + 9 tools + 3 supplemental)
 skills/               # 3 Claude Code skills (pipeline reference, runner, multi-model dispatch)
+agent-skills/         # 2 shared agent skills packaged for Claude Code and Gemini installs
 ```
 
 ### Testing
@@ -878,7 +881,7 @@ skills/               # 3 Claude Code skills (pipeline reference, runner, multi-
 ### Contributing
 
 1. Meta-prompt content lives in `pipeline/` — edit the relevant `.md` file
-2. If you changed adapter behavior, run `scaffold build` in a test project and inspect the generated artifacts under `.scaffold/generated/`.
+2. If you changed adapter behavior, run `scaffold build` in a test project and inspect the generated artifacts under `.scaffold/generated/` plus the Gemini project-local outputs (`.agents/skills/`, `GEMINI.md`, `.gemini/commands/scaffold/`).
 3. Run `make check-all` (lint + type-check + test + evals) before submitting
 4. Knowledge entries live in `knowledge/` — follow the existing frontmatter schema
 5. ADRs documenting architectural decisions are in `docs/v2/adrs/`

package/agent-skills/scaffold-pipeline/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: scaffold-pipeline
+description: Static reference for scaffold pipeline ordering, dependencies, and phase structure. Use ONLY for questions about pipeline design, step ordering, or dependency constraints — NOT for status, progress, or "what's next" queries (those go through scaffold-runner).
+---
+
+# Scaffold Pipeline Reference
+
+This skill is a **static reference** for pipeline ordering and dependency constraints. It does NOT handle status checks, progress queries, or navigation.
+
+**Activation boundary:** If the user asks "where am I?", "what's next?", "pipeline status", or anything about their current progress → **do not use this skill**. The `scaffold-runner` skill handles all status/navigation via the `scaffold` CLI.
+
+Use this skill ONLY when the user asks about:
+- Pipeline design: "what phases are there?", "what's the ordering?"
+- Dependency rules: "what depends on what?", "can I run X before Y?"
+- Step reference: "what commands are in phase 3?", "is design-system optional?"
+
+## Phases
+
+16 phases, each with a slug (used in frontmatter) and display name. Canonical source: `src/types/frontmatter.ts` `PHASES` constant.
+
+| # | Slug | Display Name | Description |
+|---|------|-------------|-------------|
+| 0 | `vision` | Product Vision | Transforms your idea into a strategic vision document covering who it's for, what makes it different, and what success looks like. |
+| 1 | `pre` | Product Definition | Translates your vision into a PRD with features, personas, and success criteria, then breaks it into user stories with testable acceptance criteria. |
+| 2 | `foundation` | Project Foundation | Researches and documents technology choices, creates coding standards with linter configs, defines testing strategy, and designs directory layout. |
+| 3 | `environment` | Development Environment | Sets up local dev environment, design system (web only), git workflow with CI and worktrees, automated PR review, and AI memory persistence. |
+| 4 | `integration` | Testing Integration | Auto-detects platform and configures E2E testing — Playwright for web, Maestro for mobile. Skips for backend-only. |
+| 5 | `modeling` | Domain Modeling | Identifies core concepts (entities, relationships, invariants, events) and establishes a shared vocabulary across all docs and code. |
+| 6 | `decisions` | Architecture Decisions | Documents every significant design decision with alternatives and consequences, so future contributors know why. |
+| 7 | `architecture` | System Architecture | Designs the system blueprint — components, data flows, module structure, and extension points. |
+| 8 | `specification` | Specifications | Creates interface specs: database schema with constraints, API contracts with error codes, UX flows with accessibility. Each conditional. |
+| 9 | `quality` | Quality Gates | Reviews testing, generates test skeletons, creates eval checks, designs deployment pipeline, and conducts security review. |
+| 10 | `parity` | Platform Parity | Audits documentation for platform-specific gaps. Skips for single-platform projects. |
+| 11 | `consolidation` | Consolidation | Optimizes AGENTS.md under 200 lines and audits all workflow docs for consistency. |
+| 12 | `planning` | Planning | Decomposes stories into concrete tasks scoped to ~150 lines and 3 files max, with clear acceptance criteria. |
+| 13 | `validation` | Validation | Seven cross-cutting audits: scope creep, dependency cycles, implementability, traceability, naming drift, broken handoffs, decision completeness. |
+| 14 | `finalization` | Finalization | Applies validation findings, freezes docs, creates onboarding guide, and writes the implementation playbook. |
+| 15 | `build` | Build | Stateless TDD execution: single/multi-agent modes, session resume, quick tasks, and new feature enhancements. |
+
+## Pipeline Order
+
+| # | Phase | Command | Notes |
+|---|-------|---------|-------|
+| 1 | Product Definition | `/scaffold:create-prd` | Interactive — requires user input |
+| 2 | Product Definition | `/scaffold:review-prd` | Multi-pass PRD review |
+| 2.5 | Product Definition | `/scaffold:innovate-prd` | **(optional)** Feature-level innovation |
+| 3 | Product Definition | `/scaffold:user-stories` | Covers every PRD feature |
+| 4 | Product Definition | `/scaffold:review-user-stories` | Multi-pass story review; depth 4+ adds requirements index |
+| 4.5 | Product Definition | `/scaffold:innovate-user-stories` | **(optional)** UX-level enhancements |
+| 5 | Project Foundation | `/scaffold:beads` | **(optional)** Creates AGENTS.md + task tracking |
+| 6 | Project Foundation | `/scaffold:tech-stack` | Drives all technical decisions |
+| 7 | Project Foundation | `/scaffold:coding-standards` | References tech-stack.md |
+| 8 | Project Foundation | `/scaffold:tdd` | References tech-stack.md + coding-standards.md |
+| 9 | Project Foundation | `/scaffold:project-structure` | References all Phase 2 docs |
+| 10 | Dev Environment | `/scaffold:dev-env-setup` | Creates lint/test/install commands |
+| 11 | Dev Environment | `/scaffold:design-system` | **(optional)** Frontend projects only |
+| 12 | Dev Environment | `/scaffold:git-workflow` | Branching, CI, worktrees, permissions |
+| 12.5 | Dev Environment | `/scaffold:automated-pr-review` | **(optional)** Local CLI or external reviewer |
+| 13 | Dev Environment | `/scaffold:ai-memory-setup` | Modular rules, optional MCP memory + external docs |
+| 14 | Testing Integration | `/scaffold:add-e2e-testing` | **(optional)** Playwright (web) and/or Maestro (mobile) |
+| 15 | Domain Modeling | `/scaffold:domain-modeling` | Entities, aggregates, events, bounded contexts |
+| 16 | Domain Modeling | `/scaffold:review-domain-modeling` | 10-pass domain model review |
+| 17 | Architecture Decisions | `/scaffold:adrs` | Architecture Decision Records |
+| 18 | Architecture Decisions | `/scaffold:review-adrs` | Review for contradictions, missing decisions |
+| 19 | System Architecture | `/scaffold:system-architecture` | Components, data flows, module structure |
+| 20 | System Architecture | `/scaffold:review-architecture` | Coverage gaps, constraint violations |
+| 21 | Specifications | `/scaffold:database-schema` | **(optional)** Tables, indexes, constraints |
+| 22 | Specifications | `/scaffold:review-database` | **(optional)** Schema review |
+| 23 | Specifications | `/scaffold:api-contracts` | **(optional)** Endpoints, error codes, auth |
+| 24 | Specifications | `/scaffold:review-api` | **(optional)** API contracts review |
+| 25 | Specifications | `/scaffold:ux-spec` | **(optional)** Flows, states, accessibility |
+| 26 | Specifications | `/scaffold:review-ux` | **(optional)** UX spec review |
+| 27 | Quality Gates | `/scaffold:review-testing` | Reviews TDD strategy for coverage gaps |
+| 27.5 | Quality Gates | `/scaffold:story-tests` | Tagged test skeletons from user story ACs |
+| 28 | Quality Gates | `/scaffold:create-evals` | Generates eval checks from standards docs |
+| 29 | Quality Gates | `/scaffold:operations` | Deployment, monitoring, incident response |
+| 30 | Quality Gates | `/scaffold:review-operations` | Reviews operations runbook |
+| 31 | Quality Gates | `/scaffold:security` | Threat model, auth, data protection |
+| 32 | Quality Gates | `/scaffold:review-security` | Reviews security posture |
+| 33 | Platform Parity | `/scaffold:platform-parity-review` | **(optional)** Multi-platform projects |
+| 34 | Consolidation | `/scaffold:Codex-md-optimization` | Run BEFORE workflow-audit |
+| 35 | Consolidation | `/scaffold:workflow-audit` | Run AFTER Codex-md-optimization |
+| 36 | Planning | `/scaffold:implementation-plan` | Creates full task graph |
+| 37 | Planning | `/scaffold:implementation-plan-review` | Second pass for quality + multi-model validation (depth 4+) |
+| 38 | Validation | `/scaffold:cross-phase-consistency` | Naming, assumptions, interfaces |
+| 39 | Validation | `/scaffold:traceability-matrix` | PRD → Stories → Architecture → Tasks |
+| 40 | Validation | `/scaffold:decision-completeness` | All decisions recorded and justified |
+| 41 | Validation | `/scaffold:critical-path-walkthrough` | End-to-end critical journey trace |
+| 42 | Validation | `/scaffold:implementability-dry-run` | Simulate agent picking up tasks |
+| 43 | Validation | `/scaffold:dependency-graph-validation` | Verify task DAG is acyclic |
+| 44 | Validation | `/scaffold:scope-creep-check` | Specs stay within PRD boundaries |
+| 45 | Finalization | `/scaffold:apply-fixes-and-freeze` | Apply findings, freeze docs |
+| 46 | Finalization | `/scaffold:developer-onboarding-guide` | "Start here" for new devs/agents |
+| 47 | Finalization | `/scaffold:implementation-playbook` | Operational guide for agent execution |
+| 48 | Execution | `/scaffold:single-agent-start` | Single-agent TDD execution loop |
+| 48 | Execution | `/scaffold:multi-agent-start` | Multi-agent — one per worktree |
+
+### Phase 15 — Build (stateless, on-demand)
+
+6 steps. Available once Phase 14 is complete. These steps are **stateless** — they don't track completion state and are always available for repeated use.
+
+| Order | Step | Description |
+|-------|------|-------------|
+| 1510 | single-agent-start | Start single-agent TDD execution loop |
+| 1520 | single-agent-resume | Resume single-agent work after a break |
+| 1530 | multi-agent-start | Start multi-agent execution loop in a worktree |
+| 1540 | multi-agent-resume | Resume multi-agent work after a break |
+| 1550 | quick-task | Create a focused task for a bug fix, refactor, or small improvement |
+| 1560 | new-enhancement | Add a new feature to an existing project |
+
+## Standalone Commands
+
+| Command | When to Use |
+|---------|-------------|
+| `/scaffold:single-agent-resume` | Resume work after a break |
+| `/scaffold:multi-agent-resume` | Resume multi-agent work after a break |
+| `/scaffold:new-enhancement` | Add a feature to an existing project |
+| `/scaffold:quick-task` | Create a focused task for a bug fix, refactor, or small improvement |
+| `/scaffold:version-bump` | Bump version and update changelog without tagging or releasing |
+| `/scaffold:release` | Create a versioned release with changelog and GitHub release |
+| `/scaffold:prompt-pipeline` | Show the full pipeline reference |
+| `/scaffold:dashboard` | Open visual pipeline dashboard in browser |
+
+## Execution Model
+
+### Two Parallel Tracks
+
+After Phase 1 (Product Definition), the pipeline splits into **two independent tracks** that can run concurrently. They converge at Phase 12 (Planning).
+
+```
+                           ┌─ Track A: Infrastructure ──────────────────────┐
+                           │                                                │
+Phase 1                    │  Phase 2 (foundation)                          │
+create-prd ─→ review-prd  │    tech-stack → coding-standards → tdd         │
+    ↓                      │                     ↓                          │
+user-stories               │    project-structure → dev-env-setup           │
+    ↓                      │         ↓                                      │
+review-user-stories ──┐    │    git-workflow → Codex-md-optimization       │
+                      │    │         ↓              ↓                       │
+                      │    │    ai-memory-setup  workflow-audit              │
+                      │    │                                                │
+                      │    └────────────────────────────────────────────────┘
+                      │
+                      │    ┌─ Track B: Domain & Quality ───────────────────┐
+                      │    │                                                │
+                      └──→ │  Phase 5-8: domain-modeling → adrs →           │
+                           │    system-architecture → specs (DB/API/UX)     │
+                           │                                                │
+                           │  Phase 9: tdd → review-testing → operations    │
+                           │    → security (+ reviews for each)             │
+                           │                                                │
+                           └────────────────────────────────────────────────┘
+                                              ↓
+                              ┌───────────────┴───────────────┐
+                              │   Phase 12: Planning          │
+                              │   (convergence point —        │
+                              │    depends on both tracks)    │
+                              └───────────────┬───────────────┘
+                                              ↓
+                              Phase 13: Validation (7 parallel checks)
+                                              ↓
+                              Phase 14: Finalization → Execution
+```
+
+### How Order Numbers Work
+
+The `order` field is a **tiebreaker**, not a sequence number. Execution order is determined by:
+
+1. **Dependency graph** (primary) — topological sort ensures prerequisites complete first
+2. **Order field** (secondary) — when multiple steps are eligible simultaneously, lower order runs first
+
+Order numbers are **phase-aligned**: Phase N uses orders in the N00 range (Phase 1 = 100s, Phase 2 = 200s, etc.). This makes it easy to identify which phase a step belongs to from its order alone.
+
+### Which Phases Can Run in Parallel
+
+Steps within the same track that don't depend on each other can run in parallel (in separate sessions/worktrees):
+
+- **Track A** and **Track B** are fully independent until Phase 12
+- Within Track B, specification steps (Phase 8) can parallelize: DB schema, API contracts, and UX spec all depend on review-architecture but not each other
+- Validation steps (Phase 13) all depend on implementation-plan-review but not each other — all 7 can run in parallel
+
+## Critical Ordering Constraints
+
+1. **Tech Stack before Coding Standards and TDD** — they reference it
+2. **Dev Setup before Git Workflow** — Git Workflow references lint/test commands
+3. **Git Workflow before AI Memory Setup** — memory rules are extracted from project docs
+4. **User Stories before Domain Modeling** — domain models derive from stories
+5. **Domain Modeling → ADRs → Architecture** — linear chain through modeling phases
+6. **Architecture before Specification** — DB, API, UX specs derive from architecture (can parallelize)
+7. **TDD → Review Testing → Operations → Security** — quality gate chain
+8. **Both tracks converge at Implementation Plan** — depends on tdd, operations, security, AND review-architecture
+9. **All 7 Validation checks before Apply Fixes & Freeze** — freeze requires all findings
+10. **Finalization before Execution** — agents need frozen docs and playbook
+
+## Status & Navigation
+
+For all status, progress, and navigation queries, use the `scaffold-runner` skill, which delegates to the `scaffold` CLI:
+
+- `scaffold status` — current pipeline progress
+- `scaffold status --compact` — show only actionable steps (pending/in-progress)
+- `scaffold next` — next eligible steps
+- `scaffold list` — full pipeline with status indicators
+- `scaffold skip <step> [<step2>...] --reason "..."` — skip one or more steps
+- `scaffold reset <step> --force` — reset a step to re-run it