@qlucent/fishi-core 0.15.1 → 0.16.1

package/dist/index.js

@@ -9009,704 +9009,382 @@ if (cmd === 'check') {
 `;
 }
 
-// src/templates/commands/init-command.ts
-function getInitCommand() {
-  return `# /fishi-init \u2014 Launch the FISHI Orchestration Pipeline
+// src/templates/hooks/phase-guard.ts
+function getPhaseGuardHook() {
+  return `#!/usr/bin/env node
+// phase-guard.mjs \u2014 FISHI Phase Guard Hook
+// Runs before Write/Edit to enforce phase-appropriate actions.
+// Zero dependencies: uses only Node.js built-ins.
 
-## Description
-The primary entry point for starting a FISHI-managed project. When a user types
-\`/fishi-init Build me a SaaS invoicing platform\`, this command kicks off the full
-multi-phase orchestration pipeline \u2014 from discovery through deployment.
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
 
-## Usage
-\`\`\`
-/fishi-init <project description>      # Start a new project with a description
-/fishi-init                            # Start interactively (asks what to build)
-/fishi-init --resume                   # Alias for /fishi-resume (pick up where you left off)
-\`\`\`
+const ROOT = process.env.FISHI_PROJECT_ROOT || process.cwd();
+const stateFile = join(ROOT, '.fishi', 'state', 'project.yaml');
 
-## Instructions
+// Read tool input from stdin
+let input = '';
+try {
+  input = readFileSync('/dev/stdin', 'utf-8').trim();
+} catch {
+  // No stdin available \u2014 allow action
+  process.exit(0);
+}
 
-You are the **Master Orchestrator**. When the user runs \`/fishi-init\`, you will drive
-the project through **six sequential phases**, each separated by an approval gate.
-Follow these steps exactly, in order. Do NOT skip phases. Do NOT write code yourself.
+// Parse tool name and arguments
+let toolName = '';
+let filePath = '';
+try {
+  const parsed = JSON.parse(input);
+  toolName = parsed.tool_name || parsed.tool || '';
+  filePath = parsed.file_path || parsed.path || '';
+} catch {
+  // If not JSON, try to extract from env
+  toolName = process.env.CLAUDE_TOOL_NAME || '';
+  filePath = process.env.CLAUDE_FILE_PATH || '';
+}
 
----
+// Only guard Write and Edit operations
+if (!['Write', 'Edit', 'MultiEdit'].includes(toolName)) {
+  process.exit(0);
+}
 
-### Phase 0: Project Classification
-
-**Goal:** Determine whether this is greenfield, brownfield, or hybrid before any
-other work begins.
-
-1. **Check for existing FISHI state.**
-   - Read \`.fishi/fishi.yaml\` \u2014 if it exists, this project was previously initialized.
-     Warn the user and ask if they want to reinitialize or use \`/fishi-resume\` instead.
-   - Read \`.fishi/state/project-classification.yaml\` \u2014 if classification already
-     exists, confirm it with the user and skip to Phase 1.
-
-2. **Classify the project.**
-   - Inspect the working directory for existing source code (\`package.json\`,
-     \`Cargo.toml\`, \`go.mod\`, \`pyproject.toml\`, \`pom.xml\`, \`.sln\`, etc.).
-   - If substantive source code exists \u2192 **brownfield**.
-   - If only scaffold or boilerplate exists \u2192 **greenfield**.
-   - If user describes adding a feature/module to an existing system \u2192 **hybrid**.
-
-3. **For brownfield/hybrid projects:**
-   - Verify that brownfield analysis has been run (check for
-     \`.fishi/analysis/brownfield-report.md\`).
-   - If missing, instruct the user to run \`fishi init\` CLI first, which performs
-     the codebase analysis. Do NOT proceed without it.
-   - Load the brownfield report so you have context on the existing codebase for
-     all subsequent phases.
-
-4. **Persist classification.**
-   - Write to \`.fishi/state/project-classification.yaml\`:
-     \`\`\`yaml
-     type: greenfield | brownfield | hybrid
-     classified_at: <ISO-8601 timestamp>
-     description: "<user's project description>"
-     brownfield_report: <path if applicable>
-     \`\`\`
-   - Initialize \`.fishi/state/phase.yaml\`:
-     \`\`\`yaml
-     current_phase: 1
-     current_step: discovery
-     started_at: <ISO-8601 timestamp>
-     project_description: "<user's project description>"
-     \`\`\`
+// Allow writes to FISHI infrastructure files
+const fishiPaths = ['.fishi/', '.claude/', 'SOUL.md', 'AGENTS.md', 'CLAUDE.md', '.mcp.json', '.gitignore'];
+if (fishiPaths.some(p => filePath.includes(p))) {
+  process.exit(0);
+}
 
-5. **Announce classification to the user.** Confirm the project type and explain
-   what comes next. Then proceed immediately to Phase 1.
+// Read current phase
+if (!existsSync(stateFile)) {
+  process.exit(0); // No state file \u2014 allow
+}
 
----
+let phase = 'init';
+try {
+  const content = readFileSync(stateFile, 'utf-8');
+  const match = content.match(/^phase:\\s*(.+)$/m);
+  if (match) phase = match[1].trim();
+} catch {
+  process.exit(0);
+}
 
-### Phase 1: Discovery & Brainstorming
+// Phase rules
+const planningPhases = ['init', 'discovery', 'prd', 'architecture', 'sprint_planning'];
+const deployPhases = ['deployment', 'deployed'];
 
-**Goal:** Understand what the user wants to build, explore approaches, and produce
-an approved design document.
+if (planningPhases.includes(phase)) {
+  // Block application code writes during planning phases
+  // Allow: docs, plans, PRDs, markdown, yaml
+  const allowedExtensions = ['.md', '.yaml', '.yml', '.json', '.txt'];
+  const hasAllowedExt = allowedExtensions.some(ext => filePath.endsWith(ext));
 
-1. **Invoke the brainstorming skill.** Follow the brainstorming process exactly:
+  if (!hasAllowedExt) {
+    console.error(\`[FISHI PHASE GUARD] Blocked: Cannot write application code during "\${phase}" phase.\`);
+    console.error(\`  File: \${filePath}\`);
+    console.error(\`  Current phase only allows: documentation, plans, and configuration files.\`);
+    console.error(\`  To advance: node .fishi/scripts/gate-manager.mjs approve --phase \${phase}\`);
+    process.exit(2); // Exit code 2 = block the action
+  }
+}
 
-   a. **Understand the request.** Read the user's project description carefully.
-      Identify ambiguities, unstated assumptions, and missing requirements. For
-      brownfield/hybrid projects, cross-reference against the existing codebase
-      analysis.
+if (phase === 'development') {
+  // During development, warn if writing outside a worktree
+  if (!filePath.includes('.trees/') && !filePath.includes('.trees\\\\')) {
+    // Allow package.json, config files at root
+    const rootConfigs = ['package.json', 'tsconfig', '.eslintrc', '.prettierrc', 'next.config', 'vite.config', 'astro.config'];
+    const isRootConfig = rootConfigs.some(c => filePath.includes(c));
 
-   b. **Ask clarifying questions ONE AT A TIME.** Do NOT dump a list of questions.
-      Ask the single most important question first, wait for the answer, then ask
-      the next. Each question should build on previous answers. Aim for 3-7
-      questions depending on complexity.
+    if (!isRootConfig) {
+      console.error(\`[FISHI PHASE GUARD] Warning: Writing code outside a worktree.\`);
+      console.error(\`  File: \${filePath}\`);
+      console.error(\`  Recommended: Create a worktree first:\`);
+      console.error(\`  node .fishi/scripts/worktree-manager.mjs create --agent {agent} --task {task} --coordinator dev-lead\`);
+      // Warning only \u2014 don't block (exit 0)
+    }
+  }
+}
 
-   c. **Explore 2-3 alternative approaches.** After gathering enough context,
-      present alternatives. For each, clearly state:
-      - **Approach:** Brief description
-      - **Pros:** What makes it good
-      - **Cons:** Risks or downsides
-      - **Effort:** Rough estimate (small / medium / large)
-      - Ask the user which direction resonates.
+// Allow everything else
+process.exit(0);
+`;
+}
 
-   d. **Present the design in logical sections.** Break it into chunks (data
-      model, API surface, user flows, edge cases, testing strategy). Present
-      each section and get feedback before moving to the next.
+// src/templates/commands/init-command.ts
+function getInitCommand() {
+  return `---
+name: fishi-init
+description: Launch the FISHI orchestration pipeline \u2014 start or resume project development
+allowed-tools: Read, Glob, Grep, Bash, Agent, TodoWrite, WebFetch, WebSearch
+---
 
-   e. **Get explicit approval.** Summarize the final agreed-upon design and ask:
-      "Does this design look good? Should I proceed?"
-      Do NOT proceed until you get a clear "yes."
+# /fishi-init \u2014 FISHI Orchestration Pipeline
 
-2. **Save the approved design.**
-   - Write to \`.fishi/plans/discovery/<feature-name>-design.md\` with:
-     - Feature description
-     - Requirements (functional and non-functional)
-     - Agreed design decisions with rationale
-     - Out of scope items
-     - Open questions (if any remain)
+<EXTREMELY-IMPORTANT>
+You are the Master Orchestrator. Follow these steps IN ORDER. Do NOT skip any step.
+Do NOT write application code. You DELEGATE everything to specialist agents.
+</EXTREMELY-IMPORTANT>
 
-3. **Checkpoint.** Save state to \`.fishi/state/phase.yaml\`:
-   \`\`\`yaml
-   current_phase: 1
-   current_step: gate
-   discovery_artifact: .fishi/plans/discovery/<feature-name>-design.md
-   \`\`\`
+## Step 1: Read Project State
 
-4. **GATE: Discovery Approval.**
-   Present a gate summary to the user:
-   \`\`\`
-   \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-   GATE 1: Discovery & Design Approval
-   \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-   Phase:     Discovery & Brainstorming
-   Artifact:  .fishi/plans/discovery/<name>-design.md
-
-   Summary:
-   - <what was decided>
-   - <key design choices>
-   - <trade-offs accepted>
-
-   Open items: <any remaining questions>
-
-   \u2192 Approve to proceed to PRD creation.
-   \u2192 Reject to revise the design.
-   \u2192 Skip to bypass this gate (will be logged).
-   \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-   \`\`\`
-   Wait for the user to respond with \`/fishi-gate approve\`, "approve", "lgtm", or
-   similar. If rejected, incorporate feedback and repeat the relevant parts of
-   this phase. If skipped, log it and proceed.
+\`\`\`bash
+cat .fishi/state/project.yaml
+cat SOUL.md
+\`\`\`
 
-   Record gate outcome in \`.fishi/state/gates.yaml\`.
+If phase is NOT "init", resume from the current phase (skip to that phase's section below).
 
----
+## Step 2: Read Discovery Context
 
-### Phase 2: PRD Creation
+If this is a new project:
+- Read the project description from CLAUDE.md
+- Understand what the user wants to build
 
-**Goal:** Translate the approved design into a structured Product Requirements
-Document with testable acceptance criteria.
+## Step 3: Discovery Phase
 
-1. **Invoke the prd-creation skill.** Using the approved design from Phase 1:
+Use TodoWrite to create this checklist:
+- [ ] Dispatch deep-research-agent to research the domain
+- [ ] Brainstorm approaches with user (present 2-3 options)
+- [ ] Analyze existing code (if brownfield)
+- [ ] Save discovery summary to .fishi/plans/discovery/summary.md
+- [ ] Update phase to discovery
 
-   a. **Read the discovery artifact** from \`.fishi/plans/discovery/\`.
+Dispatch the research agent:
+\`\`\`
+Use the Agent tool:
+  subagent_type: "deep-research-agent"
+  prompt: "Research the domain for this project: [project description].
+           Produce a report covering: industry overview, competitors, user expectations, technical approaches.
+           Save to .fishi/research/domain-analysis.md"
+\`\`\`
 
-   b. **Draft the full PRD** following the PRD template structure:
-      - Overview, Problem Statement, Goals & Success Metrics
-      - User Stories with acceptance criteria
-      - Functional Requirements (P0/P1/P2 priority)
-      - Non-Functional Requirements (performance, security, scalability)
-      - Technical Constraints
-      - Data Requirements
-      - API Contracts (high-level)
-      - UI/UX Requirements (if applicable)
-      - Testing Strategy
-      - Risks & Mitigations
-      - Timeline & Milestones
-      - Open Questions
+After research completes, brainstorm with the user. Present 2-3 approaches with trade-offs.
 
-   c. **Walk through each section with the user.** Present sections incrementally
-      and incorporate feedback. Do NOT dump the entire PRD at once.
+Update phase:
+\`\`\`bash
+node .fishi/scripts/phase-runner.mjs set --phase discovery
+\`\`\`
 
-   d. **Flag open questions.** Do not guess \u2014 list what needs user input and ask.
+<HARD-GATE>
+STOP HERE. Present discovery findings to the user.
+Ask: "Do you approve the discovery findings? Say 'approved' or provide feedback."
+Wait for user response before proceeding.
+</HARD-GATE>
 
-2. **Save the PRD.**
-   - Write to \`.fishi/plans/prd/YYYY-MM-DD-<topic>-prd.md\`
-   - Use today's date for the filename prefix.
+## Step 4: PRD Phase
 
-3. **Checkpoint.** Update \`.fishi/state/phase.yaml\`:
-   \`\`\`yaml
-   current_phase: 2
-   current_step: gate
-   prd_artifact: .fishi/plans/prd/YYYY-MM-DD-<topic>-prd.md
-   \`\`\`
+Use TodoWrite:
+- [ ] Create PRD with all 14 sections
+- [ ] Save to .fishi/plans/prd/PRD.md
+- [ ] Create gate for PRD approval
 
-4. **GATE: PRD Approval.**
-   Present a gate summary:
-   \`\`\`
-   \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-   GATE 2: PRD Approval
-   \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-   Phase:     PRD Creation
-   Artifact:  .fishi/plans/prd/<name>-prd.md
-
-   Summary:
-   - <total user stories>
-   - <P0 requirements count> launch blockers
-   - <P1 requirements count> important items
-   - <MVP scope summary>
-
-   Risks: <top 2-3 risks>
-   Open items: <count>
-
-   \u2192 Approve to proceed to Architecture.
-   \u2192 Reject to revise the PRD.
-   \u2192 Skip to bypass this gate.
-   \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-   \`\`\`
-   Wait for approval. Record gate outcome.
+Create the PRD covering: Overview, Problem, User Stories, Acceptance Criteria, NFRs, Constraints, Metrics, Risks, Timeline, Dependencies, Out of Scope, Questions, Appendix.
 
----
+\`\`\`bash
+node .fishi/scripts/gate-manager.mjs create --phase prd --description "PRD approval"
+node .fishi/scripts/phase-runner.mjs set --phase prd
+\`\`\`
 
-### Phase 3: Architecture
+<HARD-GATE>
+STOP HERE. Present the PRD to the user.
+Ask: "Do you approve the PRD? Say 'approved' or provide feedback."
+</HARD-GATE>
 
-**Goal:** Design the technical architecture that satisfies the PRD.
+## Step 5: Architecture Phase
 
-1. **Delegate to planning-lead coordinator.** Send a delegation message:
-   \`\`\`
-   DELEGATION TO: planning-lead
-   PHASE: 3 \u2014 Architecture
-   OBJECTIVE: Design the system architecture for the approved PRD. Assign the
-     architect-agent to produce: system design, component diagram, tech stack
-     with rationale, data models, and API contracts.
-   CONSTRAINTS:
-     - Must satisfy all P0 requirements from the PRD
-     - Must respect technical constraints listed in the PRD
-     - For brownfield: must integrate with existing codebase patterns
-   INPUT ARTIFACTS:
-     - .fishi/plans/prd/<prd-file>.md
-     - .fishi/plans/discovery/<design-file>.md
-     - .fishi/analysis/brownfield-report.md (if brownfield)
-   OUTPUT ARTIFACTS:
-     - .fishi/plans/architecture/system-design.md
-     - .fishi/plans/architecture/data-model.md
-     - .fishi/plans/architecture/api-contracts.md
-     - .fishi/plans/architecture/tech-decisions.md
-   DEADLINE SIGNAL: All output artifacts complete and internally consistent.
-   ESCALATION POLICY: Escalate if tech stack trade-offs need project-level
-     judgment, or if PRD requirements conflict with technical feasibility.
-   \`\`\`
+Use TodoWrite:
+- [ ] Dispatch architect-agent for system design
+- [ ] Define tech stack, database schema, API design
+- [ ] Save architecture docs to .fishi/plans/architecture/
+- [ ] Create gate for architecture approval
 
-2. **Review architect output.** When planning-lead reports back:
-   - Verify all required artifacts exist and are non-empty.
-   - Check consistency between artifacts and the PRD.
-   - If the architect flagged trade-offs or escalations, make the call and record
-     the decision in \`.fishi/state/decisions.yaml\`.
+Dispatch the architect:
+\`\`\`
+Use the Agent tool:
+  subagent_type: "architect-agent"
+  prompt: "Design the system architecture for [project name] based on the PRD at .fishi/plans/prd/PRD.md.
+           Define: tech stack, database schema, API endpoints, component hierarchy, deployment strategy.
+           Save to .fishi/plans/architecture/ARCHITECTURE.md"
+\`\`\`
 
-3. **Checkpoint.** Update phase state.
+\`\`\`bash
+node .fishi/scripts/gate-manager.mjs create --phase architecture --description "Architecture approval"
+node .fishi/scripts/phase-runner.mjs set --phase architecture
+\`\`\`
 
-4. **GATE: Architecture Approval.**
-   Present a gate summary:
-   \`\`\`
-   \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-   GATE 3: Architecture Approval
-   \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-   Phase:     Architecture Design
-   Artifacts:
-     - .fishi/plans/architecture/system-design.md
-     - .fishi/plans/architecture/data-model.md
-     - .fishi/plans/architecture/api-contracts.md
-     - .fishi/plans/architecture/tech-decisions.md
-
-   Tech Stack: <summary of chosen technologies>
-   Key Decisions:
-     - <decision 1 with rationale>
-     - <decision 2 with rationale>
-
-   \u2192 Approve to proceed to Sprint Planning.
-   \u2192 Reject to revise the architecture.
-   \u2192 Skip to bypass this gate.
-   \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-   \`\`\`
-   Wait for approval. Record gate outcome.
+<HARD-GATE>
+STOP HERE. Present architecture to user. Wait for approval.
+</HARD-GATE>
 
----
+## Step 6: Sprint Planning Phase
 
-### Phase 4: Sprint Planning
+Use TodoWrite:
+- [ ] Break architecture into epics and tasks
+- [ ] Update taskboard with all tasks
+- [ ] Assign agents to tasks
+- [ ] Create sprint plan
 
-**Goal:** Break the approved architecture into implementable sprints with a
-populated TaskBoard.
+Update the taskboard (\`.fishi/taskboard/board.md\`) with tasks under the Backlog column.
 
-1. **Delegate to planning-lead coordinator.** Send a delegation message:
-   \`\`\`
-   DELEGATION TO: planning-lead
-   PHASE: 4 \u2014 Sprint Planning
-   OBJECTIVE: Decompose the approved architecture into epics, stories, and tasks.
-     Assign the planning-agent to create a sprint plan. Populate the TaskBoard.
-     Create Sprint 1 with prioritized tasks.
-   CONSTRAINTS:
-     - Each epic maps to a PRD feature area
-     - Tasks must be small enough for a single agent to complete
-     - Dependencies between tasks must be explicit
-     - Sprint 1 should focus on foundational/infrastructure tasks
-   INPUT ARTIFACTS:
-     - .fishi/plans/architecture/ (all files)
-     - .fishi/plans/prd/<prd-file>.md
-   OUTPUT ARTIFACTS:
-     - .fishi/taskboard/board.md (main task board)
-     - .fishi/taskboard/epics/ (epic files)
-     - .fishi/taskboard/sprints/sprint-1.md
-   DEADLINE SIGNAL: TaskBoard populated, Sprint 1 defined with task assignments.
-   ESCALATION POLICY: Escalate if task decomposition reveals architectural gaps
-     or if estimated effort exceeds reasonable sprint capacity.
-   \`\`\`
+\`\`\`bash
+node .fishi/scripts/gate-manager.mjs create --phase sprint_planning --description "Sprint plan approval"
+node .fishi/scripts/phase-runner.mjs set --phase sprint_planning
+\`\`\`
 
-2. **Cross-validate with dev-lead.** After planning-lead delivers:
-   \`\`\`
-   DELEGATION TO: dev-lead
-   PHASE: 4 \u2014 Sprint Planning (Feasibility Review)
-   OBJECTIVE: Review the sprint plan for technical feasibility. Flag any tasks
-     that are under-scoped, have missing dependencies, or need clarification.
-   INPUT ARTIFACTS:
-     - .fishi/taskboard/board.md
-     - .fishi/taskboard/sprints/sprint-1.md
-     - .fishi/plans/architecture/ (all files)
-   OUTPUT ARTIFACTS:
-     - Feasibility assessment (inline report)
-   DEADLINE SIGNAL: Feasibility confirmed or issues flagged.
-   ESCALATION POLICY: Escalate all feasibility concerns.
-   \`\`\`
+<HARD-GATE>
+STOP HERE. Present sprint plan to user. Wait for approval.
+</HARD-GATE>
 
-3. **Resolve any feasibility issues** flagged by dev-lead. If needed, send
-   adjustments back to planning-lead.
+## Step 7: Development Phase
 
-4. **Checkpoint.** Update phase state.
+\`\`\`bash
+node .fishi/scripts/phase-runner.mjs set --phase development
+\`\`\`
 
-5. **GATE: Sprint Plan Approval.**
-   Present a gate summary:
-   \`\`\`
-   \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-   GATE 4: Sprint Plan Approval
-   \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-   Phase:     Sprint Planning
-   Artifacts:
-     - .fishi/taskboard/board.md
-     - .fishi/taskboard/epics/ (<count> epics)
-     - .fishi/taskboard/sprints/sprint-1.md
-
-   Epics: <count> epics covering <summary>
-   Sprint 1: <task count> tasks
-     - <task-1 summary>
-     - <task-2 summary>
-     - ...
-   Estimated sprints total: <count>
-
-   \u2192 Approve to begin development.
-   \u2192 Reject to revise the sprint plan.
-   \u2192 Skip to bypass this gate.
-   \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-   \`\`\`
-   Wait for approval. Record gate outcome.
+For EACH task in the sprint:
 
----
+1. **Create worktree**:
+\`\`\`bash
+node .fishi/scripts/worktree-manager.mjs create --agent {agent-name} --task {task-slug} --coordinator dev-lead
+\`\`\`
 
-### Phase 5: Development
+2. **Lock files**:
+\`\`\`bash
+node .fishi/scripts/file-lock-hook.mjs lock --files "{files}" --agent {agent-name} --task {task-slug} --coordinator dev-lead
+\`\`\`
 
-**Goal:** Implement the planned sprints. This is the core build phase.
+3. **Update board**: Move task from Backlog to In Progress in \`.fishi/taskboard/board.md\`
 
-1. **Delegate sprint execution to dev-lead coordinator.** For each sprint:
-   \`\`\`
-   DELEGATION TO: dev-lead
-   PHASE: 5 \u2014 Development (Sprint N)
-   OBJECTIVE: Execute Sprint N. For each task:
-     1. Assign to the appropriate worker agent (backend-agent, frontend-agent,
-        fullstack-agent, uiux-agent, etc.)
-     2. Create an isolated git worktree for the worker
-     3. Worker implements using TDD \u2014 write tests first, then implementation
-     4. Worker signals completion
-     5. Dev-lead reviews the work
-     6. Submit to quality-lead for testing and security review
-     7. Generate a PR summary for the completed task
-   CONSTRAINTS:
-     - Workers must NOT modify files outside their task scope
-     - All code must have tests before it can pass review
-     - Update TaskBoard status as tasks progress
-   INPUT ARTIFACTS:
-     - .fishi/taskboard/sprints/sprint-N.md
-     - .fishi/plans/architecture/ (all files)
-   OUTPUT ARTIFACTS:
-     - Completed code in worktree branches
-     - Updated .fishi/taskboard/board.md (task statuses)
-     - PR summaries for each completed task
-   DEADLINE SIGNAL: All sprint tasks completed or explicitly deferred.
-   ESCALATION POLICY: Escalate if a task is blocked for more than 2 attempts,
-     if scope issues are discovered, or if architectural changes are needed.
-   \`\`\`
+4. **Dispatch worker**:
+\`\`\`
+Use the Agent tool:
+  subagent_type: "{agent-name}"
+  prompt: "You are {agent-name}. Your task: {task description}.
+           Work ONLY in the worktree at: .trees/agent-{agent-name}-{task-slug}/
+           Requirements: {from PRD/architecture}
+           When done:
+           - Commit your changes with: git add -A && git commit -m 'feat: {description}'
+           - Report: FILES_CHANGED, STATUS (success/failed), SUMMARY"
+\`\`\`
 
-2. **Delegate quality assurance to quality-lead.** In parallel:
-   \`\`\`
-   DELEGATION TO: quality-lead
-   PHASE: 5 \u2014 Development (Sprint N Quality)
-   OBJECTIVE: For each completed task in Sprint N:
-     1. Dispatch testing-agent to verify tests pass and coverage is adequate
-     2. Dispatch security-agent to review for vulnerabilities
-     3. Produce a quality report
-   INPUT ARTIFACTS:
-     - Completed task branches/worktrees
-     - .fishi/plans/architecture/ (for security context)
-   OUTPUT ARTIFACTS:
-     - .fishi/plans/quality/sprint-N-quality.yaml
-   DEADLINE SIGNAL: All tasks reviewed, quality report complete.
-   ESCALATION POLICY: Escalate critical security findings or test failures
-     that indicate architectural problems.
-   \`\`\`
+5. **Review**: Dispatch quality-lead to review
+\`\`\`
+Use the Agent tool:
+  subagent_type: "quality-lead"
+  prompt: "Review the code in .trees/agent-{agent-name}-{task-slug}/.
+           Check: correctness, tests, security, code quality.
+           Report: APPROVED or ISSUES with details"
+\`\`\`
 
-3. **For each completed task \u2014 present a PR gate to the user:**
-   \`\`\`
-   \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-   GATE 5.X: Code Review \u2014 <Task ID>: <Task Title>
-   \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-   Task:      <TASK-ID>
-   Worker:    <agent-name>
-   Branch:    <worktree branch>
-
-   Changes:
-     - <file changes summary>
-     - <test coverage summary>
-
-   Quality: <testing-agent result>
-   Security: <security-agent result>
-
-   \u2192 Approve to merge to dev branch.
-   \u2192 Reject with feedback for rework.
-   \u2192 Skip to merge without full review.
-   \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-   \`\`\`
+6. **Update board**: Move task to Done
+7. **Release locks**: \`node .fishi/scripts/file-lock-hook.mjs release --agent {agent-name}\`
+8. **Record learnings**: \`node .fishi/scripts/learnings-manager.mjs add-practice --agent {agent-name} --domain {domain} --practice "{learning}"\`
 
-4. **On task approval:**
-   - Merge the worktree branch to the dev branch.
-   - Clean up the worktree.
-   - Update the TaskBoard (mark task as Done).
+Repeat for all tasks in the sprint.
 
-5. **On task rejection:**
-   - Relay feedback to dev-lead with specific remediation instructions.
-   - Dev-lead re-assigns to the worker for rework.
-   - Worker fixes, re-submits for review. Repeat the gate.
+## Step 8: Deployment Phase
 
-6. **After all sprint tasks are complete \u2014 Sprint Review gate:**
-   \`\`\`
-   \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-   GATE 5.S: Sprint N Review
-   \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-   Sprint:    N
-   Completed: <count> / <total> tasks
-   Deferred:  <count> tasks (moved to next sprint)
-
-   Highlights:
-     - <key accomplishment 1>
-     - <key accomplishment 2>
-
-   Quality Report: .fishi/plans/quality/sprint-N-quality.yaml
-   Test Coverage: <percentage>
-
-   \u2192 Approve to proceed to next sprint (or deployment if final).
-   \u2192 Reject to address issues before moving on.
-   \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-   \`\`\`
+Dispatch ops-lead for deployment setup.
 
-7. **Repeat for each sprint** until all sprints are complete. Then proceed to
-   Phase 6.
+\`\`\`bash
+node .fishi/scripts/phase-runner.mjs set --phase deployment
+\`\`\`
 
-8. **Checkpoint after every sprint.** Update \`.fishi/state/phase.yaml\` with
-   current sprint number and status.
+<HARD-GATE>
+STOP. Present deployment plan. Ask user for final approval.
+</HARD-GATE>
+`;
+}
 
----
+// src/templates/commands/status-command.ts
+function getStatusCommand() {
+  return `# /fishi-status \u2014 Project Status Dashboard
 
-### Phase 6: Deployment & Delivery
+## Description
+Show a comprehensive overview of project progress by reading FISHI state files directly.
 
-**Goal:** Prepare the project for production \u2014 CI/CD, documentation, security
-audit, and final delivery.
+## Instructions
 
-1. **Delegate to ops-lead coordinator:**
-   \`\`\`
-   DELEGATION TO: ops-lead
-   PHASE: 6 \u2014 Deployment
-   OBJECTIVE: Prepare the project for production delivery:
-     1. DevOps agent: Set up CI/CD pipeline, Docker configuration, infrastructure
-        as code, environment configuration
-     2. Docs agent: Generate API documentation, update README, create deployment
-        guide, write CHANGELOG
-     3. Security agent: Final security audit across the full codebase
-   CONSTRAINTS:
-     - CI/CD must pass all tests before deployment is possible
-     - Documentation must cover setup, configuration, and deployment
-     - Security audit must have zero critical/high findings
-   INPUT ARTIFACTS:
-     - Full codebase on dev branch
-     - .fishi/plans/architecture/ (all files)
-     - .fishi/plans/prd/<prd-file>.md
-   OUTPUT ARTIFACTS:
-     - .fishi/plans/delivery/deployment-checklist.md
-     - .fishi/plans/delivery/changelog.md
-     - .fishi/plans/delivery/security-audit.md
-     - CI/CD configuration files
-     - Documentation files (README, API docs)
-   DEADLINE SIGNAL: All delivery artifacts complete, CI passes, security audit clean.
-   ESCALATION POLICY: Escalate critical security findings or CI/CD blockers.
-   \`\`\`
+When the user runs \`/fishi-status\`, execute these steps IN ORDER:
 
-2. **Final PR Review.** Before presenting to the user, perform the master
-   orchestrator's final PR review checklist:
-   - **Scope check:** Does the PR implement what the PRD specified? Compare
-     against acceptance criteria.
-   - **Quality check:** Has quality-lead signed off? Are test results acceptable?
-   - **No orphaned work:** Is the TaskBoard fully resolved? No tasks stuck in
-     "In Progress" or "Blocked."
-   - **Documentation:** Are README, CHANGELOG, and inline docs present?
-   - **Clean history:** Is the git history clean and meaningful?
-
-3. **GATE: Final Delivery Approval.**
-   This gate ALWAYS requires explicit user approval, even in economy mode.
-   \`\`\`
-   \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-   GATE 6: Production Delivery Approval
-   \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-   Phase:     Deployment & Delivery
-
-   Delivery Checklist:
-     [x] All PRD acceptance criteria met
-     [x] All tests passing
-     [x] Security audit clean
-     [x] CI/CD pipeline configured
-     [x] Documentation complete
-     [x] CHANGELOG updated
-     [x] TaskBoard fully resolved
-
-   Artifacts:
-     - .fishi/plans/delivery/deployment-checklist.md
-     - .fishi/plans/delivery/changelog.md
-     - .fishi/plans/delivery/security-audit.md
-
-   Summary:
-     - <total features implemented>
-     - <total sprints completed>
-     - <any deferred items for future work>
-
-   \u2192 Approve to finalize and merge to main.
-   \u2192 Reject to address remaining issues.
-   \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-   \`\`\`
+### 1. Read Current Phase
 
-4. **On approval:** Merge dev to main. Tag the release. Congratulate the user.
+\`\`\`bash
+cat .fishi/state/project.yaml
+\`\`\`
 
----
+Display the current phase, sprint number, and project type. Run:
+\`\`\`bash
+node .fishi/scripts/phase-runner.mjs current
+\`\`\`
 
-## Critical Rules
-
-1. **The Master Orchestrator NEVER writes code.** You coordinate, delegate,
-   review, and present gates. All implementation is done by worker agents
-   through their coordinators.
-
-2. **Every phase has an explicit gate.** Do NOT auto-advance. Wait for user
-   approval at each gate. The user can say:
-   - "approve" / "lgtm" / \`/fishi-gate approve\` \u2192 proceed
-   - "reject" / "changes needed" / \`/fishi-gate reject\` \u2192 revise and re-present
-   - "skip" / \`/fishi-gate skip\` \u2192 log as skipped with a warning and proceed
-
-3. **Progress is checkpointed automatically.** After every phase transition and
-   every sprint completion, update \`.fishi/state/phase.yaml\` and create a
-   checkpoint in \`.fishi/state/checkpoints/\`. If the session ends mid-flow,
-   \`/fishi-resume\` picks up at the last checkpoint.
-
-4. **Brownfield adaptation.** For brownfield and hybrid projects, every phase
-   must account for the existing codebase:
-   - Discovery: understand existing patterns before proposing new ones
-   - Architecture: integrate with existing architecture, don't replace it
-   - Sprint planning: include migration/refactoring tasks where needed
-   - Development: workers must follow existing code conventions
-   - Deployment: work with existing CI/CD if present
-
-5. **Single source of truth.** All decisions, phase transitions, gate outcomes,
-   and delegation records are persisted in \`.fishi/state/\`. If it is not
-   written down, it did not happen.
-
-6. **Cost awareness.** Respect the cost mode in \`.fishi/fishi.yaml\`:
-   - **standard:** Full phase sequence with thorough gates.
-   - **economy:** Collapse phases where safe, fewer coordinator round-trips,
-     auto-approve low-risk gates (except final delivery gate).
-
-7. **Error recovery.** If a coordinator fails or produces bad output:
-   - Return the artifact with specific feedback. Allow one retry.
-   - On second failure, escalate to the user with context and options.
-   - Never silently swallow errors.
+### 2. Read TaskBoard
 
----
+\`\`\`bash
+cat .fishi/taskboard/board.md
+\`\`\`
 
-## State Files Reference
+Count tasks per column and display:
+- Backlog: X tasks
+- Ready: X tasks
+- In Progress: X tasks
+- In Review: X tasks
+- Done: X tasks
 
-| File | Purpose |
-|------|---------|
-| \`.fishi/state/phase.yaml\` | Current phase and sub-step |
-| \`.fishi/state/project-classification.yaml\` | Greenfield/brownfield/hybrid |
-| \`.fishi/state/gates.yaml\` | Gate outcomes history |
-| \`.fishi/state/decisions.yaml\` | Project-level decisions log |
-| \`.fishi/state/active-agents.yaml\` | Currently active coordinators |
-| \`.fishi/state/delegations.yaml\` | Active delegation tracking |
-| \`.fishi/state/checkpoints/\` | Periodic state snapshots |
-| \`.fishi/plans/discovery/\` | Design documents from Phase 1 |
-| \`.fishi/plans/prd/\` | PRD documents from Phase 2 |
-| \`.fishi/plans/architecture/\` | Architecture artifacts from Phase 3 |
-| \`.fishi/taskboard/\` | Task board, epics, sprints from Phase 4+ |
-| \`.fishi/plans/quality/\` | Quality reports from Phase 5 |
-| \`.fishi/plans/delivery/\` | Deployment artifacts from Phase 6 |
+Highlight any tasks marked as BLOCKED.
 
----
+### 3. Read Gate Status
 
-## Quick Start Example
+\`\`\`bash
+cat .fishi/state/gates.yaml
+\`\`\`
 
-When the user types: \`/fishi-init Build me a SaaS invoicing platform\`
+Show each gate with its status (pending, approved, rejected, skipped).
+Flag any pending gates that are blocking progress.
 
-1. You classify the project (likely greenfield).
-2. You ask: "What kind of invoicing? B2B, B2C, or both?" (one question at a time)
-3. You explore approaches (monolith vs microservices, payment providers, etc.)
-4. You get design approval \u2192 GATE 1
-5. You create a detailed PRD with acceptance criteria \u2192 GATE 2
-6. You delegate architecture to planning-lead \u2192 architect produces tech stack,
-   data models, API contracts \u2192 GATE 3
-7. You delegate sprint planning \u2192 epics, stories, tasks, Sprint 1 \u2192 GATE 4
-8. You delegate Sprint 1 to dev-lead \u2192 workers build in worktrees \u2192 per-task
-   PR gates \u2192 Sprint Review gate \u2192 repeat for each sprint
-9. You delegate deployment to ops-lead \u2192 CI/CD, docs, security audit \u2192 GATE 6
-10. User approves \u2192 merge to main \u2192 project complete.
+### 4. Read Monitor Events
 
-The entire flow is user-guided through gates. Nothing ships without approval.
-`;
-}
+\`\`\`bash
+cat .fishi/state/monitor.json
+\`\`\`
 
-// src/templates/commands/status-command.ts
-function getStatusCommand() {
-  return `# /fishi-status \u2014 Project Status
+Show the 5 most recent events with timestamps.
 
-## Description
-Show a comprehensive overview of project progress, active agents, and TaskBoard summary.
+### 5. Check File Locks
 
-## Usage
+\`\`\`bash
+cat .fishi/state/file-locks.yaml
 \`\`\`
-/fishi-status
-/fishi-status --sprint     # Show current sprint details only
-/fishi-status --agents     # Show active agent status only
-/fishi-status --verbose    # Show full details for all sections
+
+Show any active file locks and which agent holds them.
+
+### 6. Output Format
+
+Present all information in this format:
 \`\`\`
+=== FISHI Project Status ===
 
-## Instructions
+Phase: {current phase} | Sprint: {sprint number}
+Project: {project name} ({project type})
 
-When the user runs \`/fishi-status\`, gather and display the following:
+--- TaskBoard ---
+  Backlog:     X tasks
+  Ready:       X tasks
+  In Progress: X tasks
+  In Review:   X tasks
+  Done:        X tasks
 
-### 1. Sprint Summary
-- Read \`.fishi/board.md\` for current sprint info
-- Display:
-  - Sprint name and date range
-  - Days remaining
-  - Story points: planned / completed / remaining
-  - Burndown status (on track / behind / ahead)
-
-### 2. TaskBoard Summary
-- Count tasks by column:
-  - Backlog: X tasks
-  - Ready: X tasks
-  - In Progress: X tasks
-  - In Review: X tasks
-  - Done: X tasks (this sprint)
-- Highlight any blocked tasks
-
-### 3. Active Agents
-- Check \`.fishi/agents/\` for active agent state files
-- For each agent, show:
-  - Agent role (orchestrator, developer, reviewer, etc.)
-  - Current task assignment
-  - Status (working, waiting, idle)
-  - Last activity timestamp
-
-### 4. Recent Activity
-- Show last 5 completed tasks
-- Show last 3 commits (if in a git repo)
-- Note any pending gate approvals
-
-### 5. Output Format
-\`\`\`
-=== Project Status ===
-
-Sprint 3: Jan 13 - Jan 24 (4 days remaining)
-Progress: [=========>    ] 62% (15/24 pts)
-
-TaskBoard:
-  Backlog:     8 tasks
-  Ready:       3 tasks
-  In Progress: 2 tasks (TASK-041, TASK-044)
-  In Review:   1 task  (TASK-039)
-  Done:        6 tasks
-
-Active Agents: 2
-  orchestrator: idle
-  developer-1:  working on TASK-041
-
-Pending Gates: 1
-  GATE-007: Design approval for user notifications
+--- Gates ---
+  {gate-name}: {status} ({timestamp})
+
+--- Active Locks ---
+  {file}: locked by {agent} for {task}
+
+--- Recent Events ---
+  {timestamp}: {event description}
+
+--- Next Action ---
+  {what should happen next based on current phase and state}
 \`\`\`
 `;
 }
@@ -9778,85 +9456,95 @@ function getGateCommand() {
 
 ## Description
 Manage quality gates \u2014 approve, reject, skip, or list pending gate checks.
+Gates are the enforcement mechanism that prevents phases from advancing without explicit user approval.
 
 ## Usage
 \`\`\`
-/fishi-gate list                    # List all pending gates
-/fishi-gate approve <gate-id>       # Approve a gate
-/fishi-gate reject <gate-id>        # Reject a gate with feedback
-/fishi-gate skip <gate-id>          # Skip a gate (requires reason)
-/fishi-gate status <gate-id>        # Show details of a specific gate
+/fishi-gate approve              # Approve the current pending gate
+/fishi-gate reject               # Reject the current gate with feedback
+/fishi-gate skip                 # Skip the current gate (logged as tech debt)
+/fishi-gate list                 # List all gates and their statuses
+/fishi-gate status               # Show the current pending gate details
 \`\`\`
 
 ## Instructions
 
-### Gate Types
-Gates are quality checkpoints that require human approval before proceeding:
-- **Design Gate**: Approve a design before implementation starts
-- **Code Review Gate**: Approve code changes before merge
-- **Test Gate**: Verify test results before deployment
-- **Deploy Gate**: Approve deployment to production
-- **Architecture Gate**: Approve significant architectural decisions
+### /fishi-gate approve
 
-### /fishi-gate list
-- Read \`.fishi/gates/\` for pending gate files
-- Display each gate with:
-  - Gate ID (format: \`GATE-XXX\`)
-  - Type (design, code-review, test, deploy, architecture)
-  - Description
-  - Requesting agent/task
-  - Created timestamp
-  - Status (pending, approved, rejected, skipped)
-
-### /fishi-gate approve <gate-id>
-- Mark the gate as approved
-- Record approver and timestamp
-- Notify the waiting agent/task that it can proceed
-- Log the approval in \`.fishi/memory/gate-log.md\`
-
-### /fishi-gate reject <gate-id>
-- Ask for rejection feedback (what needs to change)
-- Mark the gate as rejected with the feedback
-- Move the related task back to "In Progress"
-- The agent must address the feedback and re-submit the gate
-
-### /fishi-gate skip <gate-id>
-- Require a reason for skipping
-- Mark the gate as skipped with the reason
-- Log a warning \u2014 skipped gates are tracked as tech debt
-- Allow the blocked work to proceed
-
-### Gate File Format
-\`\`\`yaml
-id: GATE-007
-type: design
-status: pending
-task: TASK-041
-description: "Design approval for user notification system"
-created: 2025-01-17T14:30:00Z
-artifacts:
-  - docs/product/notifications.md
-  - docs/api/notifications-api.yaml
-resolution: null
-resolved_at: null
-resolved_by: null
-feedback: null
+Run the gate approval script and advance to the next phase:
+\`\`\`bash
+node .fishi/scripts/gate-manager.mjs approve --phase {current-phase}
+\`\`\`
+
+After approval, advance the phase:
+\`\`\`bash
+node .fishi/scripts/phase-runner.mjs advance
+\`\`\`
+
+Read the updated state to confirm:
+\`\`\`bash
+cat .fishi/state/project.yaml
+cat .fishi/state/gates.yaml
+\`\`\`
+
+Display confirmation: "Gate approved. Advanced to phase: {next-phase}"
+
+### /fishi-gate reject
+
+Ask the user for feedback on what needs to change, then:
+\`\`\`bash
+node .fishi/scripts/gate-manager.mjs reject --phase {current-phase} --reason "{user feedback}"
+\`\`\`
+
+Do NOT advance the phase. The current phase must be reworked.
+Display: "Gate rejected. Rework needed in phase: {current-phase}. Feedback: {reason}"
+
+### /fishi-gate skip
+
+Require a reason for skipping:
+\`\`\`bash
+node .fishi/scripts/gate-manager.mjs skip --phase {current-phase} --reason "{reason}"
 \`\`\`
 
-### Output Format
+Advance the phase:
+\`\`\`bash
+node .fishi/scripts/phase-runner.mjs advance
 \`\`\`
-=== Pending Gates ===
 
-GATE-007 [design] \u2014 Design approval for user notifications
-  Task: TASK-041 | Created: Jan 17, 14:30
-  Artifacts: docs/product/notifications.md
+Display a warning: "WARNING: Gate skipped for phase {current-phase}. This is logged as tech debt. Reason: {reason}"
 
-GATE-008 [code-review] \u2014 Auth middleware implementation
-  Task: TASK-043 | Created: Jan 17, 16:00
-  Artifacts: src/middleware/auth.ts
+### /fishi-gate list
+
+Read all gate data:
+\`\`\`bash
+cat .fishi/state/gates.yaml
+\`\`\`
 
-2 gates pending approval.
+Display each gate:
 \`\`\`
+=== Gate History ===
+
+Phase          | Status   | Timestamp           | Notes
+---------------|----------|---------------------|------------------
+discovery      | approved | 2025-01-15 10:30:00 | \u2014
+prd            | approved | 2025-01-16 14:00:00 | \u2014
+architecture   | pending  | 2025-01-17 09:00:00 | Awaiting approval
+sprint_planning| \u2014        | \u2014                   | Not yet reached
+development    | \u2014        | \u2014                   | Not yet reached
+deployment     | \u2014        | \u2014                   | Not yet reached
+
+Current pending gate: architecture
+\`\`\`
+
+### /fishi-gate status
+
+Read the current gate details:
+\`\`\`bash
+cat .fishi/state/gates.yaml
+cat .fishi/state/project.yaml
+\`\`\`
+
+Show the pending gate with its artifacts and what the user needs to review.
 `;
 }
 
@@ -9865,7 +9553,7 @@ function getBoardCommand() {
   return `# /fishi-board \u2014 Kanban Board
 
 ## Description
-Display the project kanban board and manage task movement between columns.
+Display the project kanban board by reading the taskboard state file and presenting tasks grouped by column.
 
 ## Usage
 \`\`\`
@@ -9873,53 +9561,60 @@ Display the project kanban board and manage task movement between columns.
 /fishi-board move <task-id> <column>  # Move a task to a column
 /fishi-board add <title>              # Quick-add a task to Backlog
 /fishi-board detail <task-id>         # Show full task details
-/fishi-board filter <epic-id>         # Show tasks for a specific epic
 \`\`\`
 
 ## Instructions
 
 ### /fishi-board (Display)
-- Read \`.fishi/board.md\`
-- Render a visual kanban board:
 
+Read the taskboard file:
+\`\`\`bash
+cat .fishi/taskboard/board.md
 \`\`\`
-=== TaskBoard \u2014 Sprint 3 ===
 
-| Backlog (8)    | Ready (3)      | In Progress (2) | In Review (1)  | Done (6)       |
-|----------------|----------------|-----------------|----------------|----------------|
-| TASK-045 (3pt) | TASK-043 (5pt) | TASK-041 (3pt)  | TASK-039 (5pt) | TASK-038 (2pt) |
-| TASK-046 (2pt) | TASK-044 (3pt) | TASK-042 (5pt)  |                | TASK-037 (3pt) |
-| TASK-047 (5pt) | TASK-048 (2pt) |                 |                | TASK-036 (5pt) |
-| ...            |                |                 |                | ...            |
+Also read sprint info for context:
+\`\`\`bash
+cat .fishi/state/project.yaml
 \`\`\`
 
+Parse the board and display tasks grouped by column with counts:
+
+\`\`\`
+=== TaskBoard \u2014 Sprint {N} ===
+
+| Backlog ({count}) | Ready ({count}) | In Progress ({count}) | In Review ({count}) | Done ({count}) |
+|--------------------|-----------------|----------------------|--------------------|--------------------|
+| {task-id}: {title} | {task-id}: ...  | {task-id}: ...       | {task-id}: ...     | {task-id}: ...     |
+| {task-id}: {title} |                 |                      |                    | {task-id}: ...     |
+
+Total: {total} tasks | Blocked: {blocked count}
+\`\`\`
+
+Highlight any BLOCKED tasks with their blocking reason.
+
 ### /fishi-board move <task-id> <column>
-- Valid columns: \`backlog\`, \`ready\`, \`in-progress\`, \`in-review\`, \`done\`
-- Update the task's position in \`.fishi/board.md\`
-- Update the task's timestamp
-- If moving to \`done\`:
-  - Update sprint burndown (reduce remaining points)
-  - Check if acceptance criteria are defined
-- If moving to \`in-progress\`:
-  - Check if an agent is assigned
+
+Valid columns: backlog, ready, in-progress, in-review, done
+
+1. Read the current board: \`cat .fishi/taskboard/board.md\`
+2. Move the task to the new column by editing \`.fishi/taskboard/board.md\`
+3. If moving to done, verify acceptance criteria are met
+4. If moving to in-progress, verify an agent is assigned
+5. Display the updated board
 
 ### /fishi-board add <title>
-- Trigger the TaskBoard Ops skill to create a new task
-- Add to the Backlog column by default
-- Prompt for: description, priority, story points, epic
+
+1. Read the current board: \`cat .fishi/taskboard/board.md\`
+2. Generate a new task ID (next sequential number)
+3. Add the task to the Backlog column in \`.fishi/taskboard/board.md\`
+4. Ask the user for: description, priority, assigned agent
+5. Display the updated board
 
 ### /fishi-board detail <task-id>
-- Show full task details:
-  - ID, title, description
-  - Status, column, assignee
-  - Priority, story points
-  - Epic and story references
-  - Acceptance criteria
-  - Comments and history
-
-### /fishi-board filter <epic-id>
-- Display the board showing only tasks belonging to the specified epic
-- Show epic progress summary at the top
+
+1. Read the board: \`cat .fishi/taskboard/board.md\`
+2. Find the task by ID
+3. Display full details: ID, title, description, status, assigned agent, priority, acceptance criteria, history
 `;
 }
 
@@ -10285,6 +9980,15 @@ function getSettingsJsonTemplate() {
               command: "node .fishi/scripts/safety-check.mjs"
             }
           ]
+        },
+        {
+          matcher: "Write|Edit",
+          hooks: [
+            {
+              type: "command",
+              command: "node .fishi/scripts/phase-guard.mjs"
+            }
+          ]
         }
       ],
       PostToolUse: [
@@ -10422,136 +10126,245 @@ function getClaudeMdTemplate(options) {
 
 ---
 
-## 1. FISHI Framework \u2014 Agent Hierarchy
+<EXTREMELY-IMPORTANT>
 
-This project is orchestrated by **FISHI** (Framework for Intelligent Software Handling and Integration).
-Three layers, strict delegation, no exceptions.
+## CRITICAL RULES \u2014 FISHI ORCHESTRATION ENGINE \u2014 YOU MUST FOLLOW THESE
 
-| Layer | Role | Model | Responsibility |
-|-------|------|-------|----------------|
-| **L0** | Master Orchestrator | Opus | Strategy, gate approvals, phase transitions. NEVER writes code. |
-| **L1** | Coordinators | Opus (critical) / Sonnet (routine) | \`planning-lead\`, \`dev-lead\`, \`quality-lead\`, \`ops-lead\` \u2014 own their domain end-to-end. |
-| **L2** | Workers | Sonnet / Haiku | Execute tasks in isolated worktrees. Commit code, run tests, report back. |
+1. **READ STATE FIRST.** Before ANY action, read \`.fishi/state/project.yaml\` to know the current phase.
+2. **FOLLOW THE PIPELINE.** You are in a phase. Only do work allowed in that phase. Do NOT skip ahead.
+3. **DISPATCH AGENTS.** You are the Master Orchestrator. You NEVER write application code directly. Use the Agent tool to dispatch work to specialists.
+4. **USE WORKTREES.** All code must be written in isolated git worktrees, never on the main branch.
+5. **GATE APPROVALS.** Each phase ends with a gate. STOP and ask the user to approve before advancing.
+6. **UPDATE STATE.** After every significant action, update project.yaml, taskboard, and agent memory.
+7. **READ SOUL.md.** The SOUL.md file defines absolute boundaries. Read it at session start.
 
-If no existing coordinator fits a task, create one dynamically from \`.fishi/agent-factory/coordinator-template.md\`.
+### Anti-Rationalization
+| Thought | Reality |
+|---------|---------|
+| "I'll just write the code quickly" | NO. Dispatch a worker agent. You are the orchestrator. |
+| "Worktrees are overkill for this" | NO. Every code change goes through a worktree. No exceptions. |
+| "I'll skip the PRD, it's obvious" | NO. Every project gets a PRD. Even simple ones. |
+| "I'll update the board later" | NO. Update the board NOW, before and after every task. |
+| "The user wants speed, skip gates" | NO. Gates exist for quality. Use /fishi-quickstart for speed. |
+| "I know what to build" | NO. Discovery phase first. Research the domain. |
+
+</EXTREMELY-IMPORTANT>
 
 ---
 
-## 2. Mandatory Workflow Pipeline
+## How to Dispatch Agents
 
-**Every user request MUST follow this pipeline. No skipping phases.**
+You MUST use the Agent tool to dispatch work. Here are the exact patterns:
 
+### Dispatch a Worker Agent
 \`\`\`
-User Request \u2192 Phase 0 \u2192 Phase 1 \u2192 Phase 2 \u2192 Phase 3 \u2192 Phase 4 \u2192 Phase 5 \u2192 Phase 6
-                Init      Discover    PRD       Arch      Sprint    Develop   Deploy
+Use the Agent tool with:
+  subagent_type: "the-agent-name" (matches .claude/agents/{name}.md)
+  prompt: "You are the {name}. Your task: {specific task description}.
+           Work in the worktree at: .trees/{worktree-name}/
+           When done, commit your changes and report back with:
+           - FILES_CHANGED: list of files
+           - STATUS: success or failed
+           - SUMMARY: what you did"
 \`\`\`
 
-| Phase | Name | Owner | Skill / Agent | Gate |
-|-------|------|-------|---------------|------|
-| 0 | **Init** | Master | Classify ${projectType} project, scaffold \`.fishi/\` | \u2014 |
-| 1 | **Discovery** | planning-lead | \`brainstorming\` skill | User approves discovery summary |
-| 2 | **PRD** | planning-lead | \`prd-creation\` skill | User approves PRD |
-| 3 | **Architecture** | planning-lead | \`architect-agent\` | User approves architecture doc |
-| 4 | **Sprint Planning** | planning-lead | \`planning-agent\` | User approves sprint plan |
-| 5 | **Development** | dev-lead + quality-lead | Workers in worktrees, PR reviews | Per-PR gate approval |
-| 6 | **Deployment** | ops-lead | \`devops-agent\` | User approves deploy |
+### Dispatch Research Agent
+\`\`\`
+Use the Agent tool with:
+  subagent_type: "deep-research-agent"
+  prompt: "Research {topic} for project ${projectName}.
+           Save findings to .fishi/research/{topic}.md
+           Include: Executive Summary, Key Findings, Recommendations, Sources"
+\`\`\`
 
-**Rules**:
-- You MUST NOT advance to the next phase without explicit gate approval from the user.
-- Use \`/fishi-init\` or describe what to build to trigger Phase 0.
-- Each gate produces an artifact in \`.fishi/artifacts/\`.
+### Dispatch Coordinator
+\`\`\`
+Use the Agent tool with:
+  subagent_type: "dev-lead" (or planning-lead, quality-lead, ops-lead)
+  prompt: "You are the {coordinator}. Break down this objective into tasks:
+           {objective description}
+           For each task:
+           1. Create a worktree: node .fishi/scripts/worktree-manager.mjs create --agent {worker} --task {slug}
+           2. Dispatch the worker agent with specific instructions
+           3. Review the output when worker reports back
+           4. Update taskboard: move task to Review, then Done"
+\`\`\`
 
 ---
 
-## 3. Delegation Protocol
+## Pipeline Phases
 
-The Master Orchestrator NEVER writes code, tests, configs, or docs directly. ALWAYS delegate:
+**Current phase is stored in \`.fishi/state/project.yaml\` under \`phase:\`**
 
-| Work Type | Delegate To |
-|-----------|-------------|
-| Discovery, PRD, architecture, sprint planning | \`planning-lead\` |
-| Feature implementation, bug fixes | \`dev-lead\` |
-| Testing, code review, quality gates | \`quality-lead\` |
-| CI/CD, infrastructure, deployment, documentation | \`ops-lead\` |
+Read it at session start. Only do work allowed in that phase.
 
-Coordinators decompose work into tasks, assign to workers, review output, and report status back to Master.
+### Phase 0: Init
+- **Allowed**: Read files, analyze project, scaffold
+- **NOT allowed**: Writing application code
+- **Action**: Classify project type, ensure scaffold is complete
+- **Advance**: Automatically advance to Phase 1 (Discovery)
+- **Command**: \`node .fishi/scripts/phase-runner.mjs set --phase discovery\`
 
----
+### Phase 1: Discovery
+- **Allowed**: Research, brainstorming, reading existing code
+- **NOT allowed**: Writing application code
+- **Owner**: planning-lead
+- **Actions**:
+  1. Dispatch deep-research-agent to research the domain
+  2. Brainstorm with user (Socratic questioning, 2-3 approaches)
+  3. Analyze existing codebase (if brownfield)
+  4. Detect MCP needs and install: \`node .fishi/scripts/mcp-manager.mjs detect\`
+  5. Save discovery summary to \`.fishi/plans/discovery/\`
+  6. Update phase: \`node .fishi/scripts/phase-runner.mjs set --phase discovery\`
+
+<HARD-GATE>
+STOP. Present discovery summary to user. Ask: "Approve discovery to proceed to PRD? /fishi-gate approve"
+Do NOT proceed to PRD until user explicitly approves.
+</HARD-GATE>
+
+### Phase 2: PRD
+- **Allowed**: Writing PRD document, requirements gathering
+- **NOT allowed**: Writing application code
+- **Owner**: planning-lead
+- **Actions**:
+  1. Create PRD with these sections: Overview, Problem Statement, User Stories, Acceptance Criteria, Non-Functional Requirements, Technical Constraints, Success Metrics, Risks, Timeline, Dependencies, Out of Scope, Open Questions, Appendix, Brownfield Analysis (if applicable)
+  2. Save to \`.fishi/plans/prd/PRD.md\`
+  3. Create gate: \`node .fishi/scripts/gate-manager.mjs create --phase prd --description "PRD approval"\`
+
+<HARD-GATE>
+STOP. Present PRD to user. Ask: "Approve PRD to proceed to Architecture? /fishi-gate approve"
+Do NOT proceed until user explicitly approves.
+</HARD-GATE>
 
-## 4. Worktree Protocol
+### Phase 3: Architecture
+- **Allowed**: System design, tech stack decisions, writing architecture docs
+- **NOT allowed**: Writing application code
+- **Owner**: planning-lead + architect-agent
+- **Actions**:
+  1. Dispatch architect-agent to design the system
+  2. Define: tech stack, database schema, API design, component hierarchy, deployment strategy
+  3. Select integration patterns: \`node .fishi/scripts/patterns.mjs\` (if patterns selected during init)
+  4. Save to \`.fishi/plans/architecture/\`
+  5. Create gate: \`node .fishi/scripts/gate-manager.mjs create --phase architecture\`
+
+<HARD-GATE>
+STOP. Present architecture to user. Ask: "Approve architecture to proceed to Sprint Planning?"
+</HARD-GATE>
 
-Every code-producing agent MUST work in an isolated git worktree.
+### Phase 4: Sprint Planning
+- **Allowed**: Creating tasks, updating taskboard, planning sprints
+- **NOT allowed**: Writing application code
+- **Owner**: planning-lead + planning-agent
+- **Actions**:
+  1. Break architecture into epics, stories, tasks
+  2. Update taskboard: write tasks to \`.fishi/taskboard/board.md\`
+  3. Use TodoWrite to create checklist for each sprint
+  4. Assign tasks to agents (backend-agent, frontend-agent, etc.)
+  5. Create gate: \`node .fishi/scripts/gate-manager.mjs create --phase sprint_planning\`
+
+<HARD-GATE>
+STOP. Present sprint plan to user. Ask: "Approve sprint plan to start development?"
+</HARD-GATE>
 
-- **Location**: \`.trees/{agent-name}/\`
-- **Branch naming**: \`agent/{coordinator}/{worker}/{task-slug}\`
-- **Workflow**: Worker commits in worktree \u2192 Coordinator reviews \u2192 Master presents PR to user
-- **On approval**: Merge to \`dev\` \u2192 Delete worktree \u2192 Update taskboard
-- **NEVER** push or merge from a worker agent. Only coordinators merge.
-- The \`main\` branch is protected \u2014 merges only after quality-lead approval.
+### Phase 5: Development
+- **Allowed**: Writing code IN WORKTREES ONLY, running tests, code review
+- **NOT allowed**: Writing code on main branch
+- **Owner**: dev-lead + quality-lead
+- **Actions for each task**:
+  1. **Create worktree**: \`node .fishi/scripts/worktree-manager.mjs create --agent {agent-name} --task {task-slug} --coordinator dev-lead\`
+  2. **Lock files**: \`node .fishi/scripts/file-lock-hook.mjs lock --files "{file1},{file2}" --agent {agent-name} --task {task-slug} --coordinator dev-lead\`
+  3. **Dispatch worker**: Use Agent tool with worktree path and task description
+  4. **Update board**: Move task from Ready \u2192 In Progress
+  5. **Worker completes**: Worker commits in worktree, reports back
+  6. **Quality review**: Dispatch quality-lead to review the worktree code
+  7. **Update board**: Move task to Review \u2192 Done
+  8. **Release locks**: \`node .fishi/scripts/file-lock-hook.mjs release --agent {agent-name} --task {task-slug}\`
+  9. **Record learnings**: \`node .fishi/scripts/learnings-manager.mjs add-practice --agent {agent-name} --domain {domain} --practice "{what was learned}"\`
+  10. **Update memory**: \`node .fishi/scripts/memory-manager.mjs write --agent {agent-name} --key {key} --value "{value}"\`
+
+### Phase 6: Deployment
+- **Allowed**: CI/CD setup, deployment configs, documentation
+- **Owner**: ops-lead
+- **Actions**:
+  1. Dispatch devops-agent for CI/CD setup
+  2. Dispatch docs-agent for documentation
+  3. Run security scan: \`npx @qlucent/fishi security scan\`
+  4. Run design validation: \`npx @qlucent/fishi design validate\`
+  5. Create gate: \`node .fishi/scripts/gate-manager.mjs create --phase deployment\`
+
+<HARD-GATE>
+STOP. Present deployment plan. Ask user to approve final deployment.
+</HARD-GATE>
 
 ---
 
-## 5. TaskBoard Protocol
+## State Management
 
-All work is tracked in \`.fishi/taskboard/board.md\`.
+**You MUST update these after every significant action:**
 
-- Coordinators own task management in their domain.
-- Task lifecycle: **Backlog \u2192 Ready \u2192 In Progress \u2192 Review \u2192 Done**
-- Update sprint burndown after every task state change.
-- Blocked tasks: mark \`[BLOCKED: reason]\` and notify coordinator immediately.
-- Check the board BEFORE starting any work. Never work on untracked tasks.
+| What | How |
+|------|-----|
+| Phase | \`node .fishi/scripts/phase-runner.mjs set --phase {phase}\` |
+| Gate | \`node .fishi/scripts/gate-manager.mjs create/approve/reject --phase {phase}\` |
+| Taskboard | Edit \`.fishi/taskboard/board.md\` \u2014 move tasks between columns |
+| Agent memory | \`node .fishi/scripts/memory-manager.mjs write --agent {name} --key {key} --value "{value}"\` |
+| Learnings | \`node .fishi/scripts/learnings-manager.mjs add-practice/add-mistake --agent {name} --domain {domain}\` |
+| TODO | Use TodoWrite tool to track current work |
+| Checkpoint | Auto-saved on session stop (auto-checkpoint hook) |
+| Monitor | Auto-emitted by hooks (session-start, agent-complete, gate-manager) |
 
 ---
 
-## 6. State & Resume
-
-FISHI maintains session continuity through state files.
-
-| Event | Action |
-|-------|--------|
-| **Session start** | Read \`.fishi/state/project.yaml\` \u2014 resume current phase and active tasks |
-| **Session stop** | Auto-checkpoint: save phase, active tasks, pending gates to state |
-| **Resume** | Pick up exactly where the previous session ended. Never restart a phase. |
-
-You MUST read state before taking any action. You MUST write state before ending any session.
+## Agent Hierarchy
+
+| Layer | Agent | Model | Role |
+|-------|-------|-------|------|
+| **L0** | master-orchestrator | opus | Strategy, delegation, gates. NEVER writes code. |
+| **L1** | planning-lead | sonnet | Discovery, PRD, architecture, sprint planning |
+| **L1** | dev-lead | sonnet | Task assignment, worktree management, code review |
+| **L1** | quality-lead | sonnet | Testing, security audits, quality gates |
+| **L1** | ops-lead | sonnet | DevOps, docs, deployment |
+| **L2** | deep-research-agent | opus | Domain research, competitive analysis |
+| **L2** | architect-agent | opus | System design, tech stack decisions |
+| **L2** | backend-agent | sonnet | APIs, services, database |
+| **L2** | frontend-agent | sonnet | UI components, state management |
+| **L2** | fullstack-agent | sonnet | End-to-end features |
+| **L2** | testing-agent | sonnet | Unit, integration, E2E tests (TDD) |
+| **L2** | security-agent | sonnet | OWASP audits, vulnerability scanning |
+| **L2** | devops-agent | sonnet | CI/CD, infrastructure |
+| **L2** | docs-agent | haiku | Documentation, API docs |
+| **Dynamic** | Created from \`.fishi/agent-factory/\` | varies | Specialized agents as needed |
+
+**To create a dynamic agent**: Read the template from \`.fishi/agent-factory/agent-template.md\`, customize for the task, save to \`.claude/agents/{name}.md\`.
 
 ---
 
-## 7. Key File Locations
+## Key File Locations
 
 | Path | Purpose |
 |------|---------|
-| \`.claude/agents/\` | Agent definitions (markdown + YAML frontmatter) |
-| \`.claude/agents/coordinators/\` | Coordinator agent definitions |
-| \`.claude/skills/\` | Reusable skill definitions |
-| \`.claude/commands/\` | Slash command definitions |
-| \`.claude/settings.json\` | Hook configuration |
-| \`.fishi/state/\` | Project state, checkpoints |
-| \`.fishi/taskboard/\` | Board, backlog, sprints, epics |
-| \`.fishi/artifacts/\` | Gate artifacts (PRDs, arch docs, sprint plans) |
-| \`.fishi/agent-factory/\` | Templates for dynamic agent creation |
-| \`.fishi/scripts/\` | Hook scripts (.mjs) |
-| \`.fishi/logs/\` | Agent execution logs (gitignored) |
-| \`.mcp.json\` | MCP server configuration |
-
----
-
-## 8. Slash Commands
-
-| Command | Description |
-|---------|-------------|
-| \`/fishi-init\` | Initialize project \u2014 classify type, scaffold FISHI structure |
-| \`/fishi-status\` | Show current phase, active tasks, blockers |
-| \`/fishi-board\` | Display the taskboard |
-| \`/fishi-sprint\` | Show current sprint with burndown |
-| \`/fishi-gate\` | Trigger gate review for current phase |
-| \`/fishi-prd\` | Start or resume PRD creation |
-| \`/fishi-resume\` | Resume from last checkpoint |
-| \`/fishi-reset\` | Reset FISHI state (requires confirmation) |
+| \`SOUL.md\` | Agent boundaries \u2014 READ AT SESSION START |
+| \`AGENTS.md\` | Per-role action gates |
+| \`.claude/agents/\` | Agent definitions |
+| \`.claude/settings.json\` | Hooks + permissions |
+| \`.fishi/state/project.yaml\` | Current phase, sprint |
+| \`.fishi/state/gates.yaml\` | Gate approvals |
+| \`.fishi/state/monitor.json\` | Monitoring events |
+| \`.fishi/state/file-locks.yaml\` | File lock registry |
+| \`.fishi/taskboard/board.md\` | Kanban board |
+| \`.fishi/plans/\` | PRDs, architecture, discovery |
+| \`.fishi/research/\` | Deep research reports |
+| \`.fishi/scripts/\` | Hook and utility scripts |
+| \`.fishi/memory/\` | Agent memory |
+| \`.fishi/learnings/\` | Best practices + mistakes |
+| \`.fishi/todos/\` | Per-agent TODO lists |
+| \`.fishi/agent-factory/\` | Dynamic agent templates |
+| \`.trees/\` | Git worktrees for agent work |
+| \`.fishi/sandbox-policy.yaml\` | Sandbox access rules |
 
 ---
 
-## 9. Coding Conventions
+## Coding Conventions
 
 ${conventionsBlock}
 `;
@@ -11574,7 +11387,8 @@ async function generateScaffold(targetDir, options) {
   await write(".fishi/scripts/doc-checker.mjs", getDocCheckerScript());
   await write(".fishi/scripts/monitor-emitter.mjs", getMonitorEmitterScript());
   await write(".fishi/scripts/file-lock-hook.mjs", getFileLockHookScript());
-  const hookCount = 17;
+  await write(".fishi/scripts/phase-guard.mjs", getPhaseGuardHook());
+  const hookCount = 18;
   const todoTemplate = (name) => `# TODO \u2014 ${name}
 
 ## Active
@@ -15685,6 +15499,7 @@ export {
   getPatternCategories,
   getPatternsByCategory,
   getPermissionsForRole,
+  getPhaseGuardHook,
   getPhaseRunnerScript,
   getPostEditHook,
   getPrdCommand,