@arsxxi/iterative-dev-workflow 1.0.1 → 1.0.2

package/.opencode/commands/phase-2-step-4.md

@@ -1,67 +1,67 @@
----
-description: "Phase 2 Step 4: High-Fidelity Design"
-argument-hint: [project name]
----
-
-## Step 0 — find which project this is for
-
-Before anything else, figure out which project this command applies to:
-
-1. If you were given a project name after the slash (e.g. `/phase-2-step-4 my-project`), use it.
-2. Otherwise, look at the subfolders under `.workflow/`:
-   - Exactly one folder → use it. Tell the user which project you picked (e.g. "Working on
-     `my-project`"), so it's never a silent guess.
-   - Two or more folders → ask the user once which project this is for. To make the question
-     useful, show the first line of each project's `00-context.md`, not just the folder name.
-   - No folders → stop and tell the user to run `/kickoff` first. Don't proceed.
-
-# Phase 2 Step 4: High-Fidelity Design
-
-## Purpose
-Create High-Level Visualizations for the Component Architecture of the chosen design, using Mermaid.js syntax.
-
-## Steps
-
-1. **Check for the previous result** from Step 3 (Quality Attribute). If it's empty or not generated, DO NOT PROCEED TO EXECUTE THIS STEP — remind the user.
-
-2. **Remind the user to double-check Step 3's result before proceeding.** Present this to the user:
-
-   > Step 3 gave you the chosen design according to the Quality Attributes you designed
-   > previously. Make sure to double-check the results from Step 3 and do your own assessment of
-   > the results given by the AI agent in Step 3. Make sure you select the correct design, not
-   > just bias from the AI's results.
-
-3. **Ask the user to explain their chosen design.** Present this to the user:
-
-   > Briefly explain the design you've selected from the previous phase, and explain from your
-   > opinion why you selected that design. Or if you have your own thoughts/modification, let the
-   > AI agent know here.
-
-   Then stop and wait for the user's explanation. Do not proceed to the analysis/diagram below
-   until they've explained their chosen design.
-
-4. **Analyze the chosen design.** Once the user has explained their chosen design, do a deep
-   dive and meticulous analysis on that chosen design.
-
-5. **Create the System Context Diagram.** Using Mermaid.js syntax, create a System Context
-   Diagram that defines the boundaries of the current solution (feature, system, etc.) we are
-   working on, and shows how the design sits within the whole app.
-
-Once this diagram is done, stop. The User Journey diagram is a separate step -
-`/phase-2-step-5` - run after you've reviewed this one.
-
-## Hard constraints
-
-- AVOID overengineering in the architecture itself — the diagrams should reflect a simple,
-  maintainable structure.
-- Name every box/component in the diagrams using plain-language intent, not jargon.
-
-## Output
-- The user's explanation of their chosen design (and any modifications)
-- Analysis of the chosen design
-- System Context Diagram (Mermaid.js)
-
-## Trigger
-```
-$ARGUMENTS = "project name"
-```
+---
+description: "Phase 2 Step 4: High-Fidelity Design"
+argument-hint: [project name]
+---
+
+## Step 0 — find which project this is for
+
+Before anything else, figure out which project this command applies to:
+
+1. If you were given a project name after the slash (e.g. `/phase-2-step-4 my-project`), use it.
+2. Otherwise, look at the subfolders under `.workflow/`:
+   - Exactly one folder → use it. Tell the user which project you picked (e.g. "Working on
+     `my-project`"), so it's never a silent guess.
+   - Two or more folders → ask the user once which project this is for. To make the question
+     useful, show the first line of each project's `00-context.md`, not just the folder name.
+   - No folders → stop and tell the user to run `/kickoff` first. Don't proceed.
+
+# Phase 2 Step 4: High-Fidelity Design
+
+## Purpose
+Create High-Level Visualizations for the Component Architecture of the chosen design, using Mermaid.js syntax.
+
+## Steps
+
+1. **Check for the previous result** from Step 3 (Quality Attribute). If it's empty or not generated, DO NOT PROCEED TO EXECUTE THIS STEP — remind the user.
+
+2. **Remind the user to double-check Step 3's result before proceeding.** Present this to the user:
+
+   > Step 3 gave you the chosen design according to the Quality Attributes you designed
+   > previously. Make sure to double-check the results from Step 3 and do your own assessment of
+   > the results given by the AI agent in Step 3. Make sure you select the correct design, not
+   > just bias from the AI's results.
+
+3. **Ask the user to explain their chosen design.** Present this to the user:
+
+   > Briefly explain the design you've selected from the previous phase, and explain from your
+   > opinion why you selected that design. Or if you have your own thoughts/modification, let the
+   > AI agent know here.
+
+   Then stop and wait for the user's explanation. Do not proceed to the analysis/diagram below
+   until they've explained their chosen design.
+
+4. **Analyze the chosen design.** Once the user has explained their chosen design, do a deep
+   dive and meticulous analysis on that chosen design.
+
+5. **Create the System Context Diagram.** Using Mermaid.js syntax, create a System Context
+   Diagram that defines the boundaries of the current solution (feature, system, etc.) we are
+   working on, and shows how the design sits within the whole app.
+
+Once this diagram is done, stop. The User Journey diagram is a separate step -
+`/phase-2-step-5` - run after you've reviewed this one.
+
+## Hard constraints
+
+- AVOID overengineering in the architecture itself — the diagrams should reflect a simple,
+  maintainable structure.
+- Name every box/component in the diagrams using plain-language intent, not jargon.
+
+## Output
+- The user's explanation of their chosen design (and any modifications)
+- Analysis of the chosen design
+- System Context Diagram (Mermaid.js)
+
+## Trigger
+```
+$ARGUMENTS = "project name"
+```

package/.opencode/commands/phase-2-step-5.md

@@ -1,34 +1,34 @@
----
-description: "Phase 2 Step 5: User Journey"
-argument-hint: [project name]
----
-
-## Step 0 — find which project this is for
-
-Before anything else, figure out which project this command applies to:
-
-1. If you were given a project name after the slash (e.g. `/phase-2-step-5 my-project`), use it.
-2. Otherwise, look at the subfolders under `.workflow/`:
-   - Exactly one folder → use it. Tell the user which project you picked (e.g. "Working on
-     `my-project`"), so it's never a silent guess.
-   - Two or more folders → ask the user once which project this is for. To make the question
-     useful, show the first line of each project's `00-context.md`, not just the folder name.
-   - No folders → stop and tell the user to run `/kickoff` first. Don't proceed.
-
-# Phase 2 Step 5: User Journey
-
-## Purpose
-Create a User Journey Diagram using Mermaid.js syntax for the chosen design from Step 4 (High-Fidelity Design).
-
-## Steps
-
-1. **Check for the previous result** from Step 4 (High-Fidelity Design). If it's empty or not generated, DO NOT PROCEED — remind the user.
-2. **Create the User Journey Diagram** using Mermaid.js syntax, mapping the user's interaction flow through the system.
-
-## Output
-- User Journey Diagram (Mermaid.js)
-
-## Trigger
-```
-$ARGUMENTS = "project name"
-```
+---
+description: "Phase 2 Step 5: User Journey"
+argument-hint: [project name]
+---
+
+## Step 0 — find which project this is for
+
+Before anything else, figure out which project this command applies to:
+
+1. If you were given a project name after the slash (e.g. `/phase-2-step-5 my-project`), use it.
+2. Otherwise, look at the subfolders under `.workflow/`:
+   - Exactly one folder → use it. Tell the user which project you picked (e.g. "Working on
+     `my-project`"), so it's never a silent guess.
+   - Two or more folders → ask the user once which project this is for. To make the question
+     useful, show the first line of each project's `00-context.md`, not just the folder name.
+   - No folders → stop and tell the user to run `/kickoff` first. Don't proceed.
+
+# Phase 2 Step 5: User Journey
+
+## Purpose
+Create a User Journey Diagram using Mermaid.js syntax for the chosen design from Step 4 (High-Fidelity Design).
+
+## Steps
+
+1. **Check for the previous result** from Step 4 (High-Fidelity Design). If it's empty or not generated, DO NOT PROCEED — remind the user.
+2. **Create the User Journey Diagram** using Mermaid.js syntax, mapping the user's interaction flow through the system.
+
+## Output
+- User Journey Diagram (Mermaid.js)
+
+## Trigger
+```
+$ARGUMENTS = "project name"
+```

package/.opencode/commands/phase-3.md

@@ -1,45 +1,45 @@
----
-description: "Phase 3: Implementation Plan"
-argument-hint: [project name]
----
-
-## Step 0 — find which project this is for
-
-Before anything else, figure out which project this command applies to:
-
-1. If you were given a project name after the slash (e.g. `/phase-3 my-project`), use it.
-2. Otherwise, look at the subfolders under `.workflow/`:
-   - Exactly one folder → use it. Tell the user which project you picked (e.g. "Working on
-     `my-project`"), so it's never a silent guess.
-   - Two or more folders → ask the user once which project this is for. To make the question
-     useful, show the first line of each project's `00-context.md`, not just the folder name.
-   - No folders → stop and tell the user to run `/kickoff` first. Don't proceed.
-
-# Phase 3: Implementation Plan
-
-## Purpose
-Write a comprehensive implementation plan based on the proposed plan and extensive architecture and design from Phase 1 and Phase 2.
-
-## Steps
-
-1. **Check for the previous result** from the previous step. If it's empty or not generated due to certain reason, then DO NOT PROCEED TO EXECUTE THIS STEP. Don't forget to remind the user if this happened.
-2. **Write a comprehensive implementation plan** based on the proposed plan (Phase 1: Analyze) and extensive architecture and design (Phase 2: Design - the chosen design, ATAM trade-offs, Quality Attribute results, System Context Diagram, and User Journey Diagram).
-
-## Constraints
-
-AVOID overengineering, PREFER simple, low-complexity implementations with the GOAL of high maintainability, AVOID jargons when naming function/methods/class/components/system, instead PRIORITIZE using layman's terms or prefer naming with the actual intentions of the code, the GOAL is ease of developer understanding and maintainability.
-
-## Iteration rule
-
-If, while writing the implementation plan, you find a problem that is actually a Design problem
-(not an implementation detail) - e.g. the architecture from Phase 2 doesn't actually support
-something needed - STOP and tell the user clearly, and recommend circling back to Phase 2. Do
-not silently work around a design flaw in the plan.
-
-## Output
-- A comprehensive implementation plan, written to `.workflow/<slug>/03-implement.md`
-
-## Trigger
-```
-$ARGUMENTS = "project name"
-```
+---
+description: "Phase 3: Implementation Plan"
+argument-hint: [project name]
+---
+
+## Step 0 — find which project this is for
+
+Before anything else, figure out which project this command applies to:
+
+1. If you were given a project name after the slash (e.g. `/phase-3 my-project`), use it.
+2. Otherwise, look at the subfolders under `.workflow/`:
+   - Exactly one folder → use it. Tell the user which project you picked (e.g. "Working on
+     `my-project`"), so it's never a silent guess.
+   - Two or more folders → ask the user once which project this is for. To make the question
+     useful, show the first line of each project's `00-context.md`, not just the folder name.
+   - No folders → stop and tell the user to run `/kickoff` first. Don't proceed.
+
+# Phase 3: Implementation Plan
+
+## Purpose
+Write a comprehensive implementation plan based on the proposed plan and extensive architecture and design from Phase 1 and Phase 2.
+
+## Steps
+
+1. **Check for the previous result** from the previous step. If it's empty or not generated due to certain reason, then DO NOT PROCEED TO EXECUTE THIS STEP. Don't forget to remind the user if this happened.
+2. **Write a comprehensive implementation plan** based on the proposed plan (Phase 1: Analyze) and extensive architecture and design (Phase 2: Design - the chosen design, ATAM trade-offs, Quality Attribute results, System Context Diagram, and User Journey Diagram).
+
+## Constraints
+
+AVOID overengineering, PREFER simple, low-complexity implementations with the GOAL of high maintainability, AVOID jargons when naming function/methods/class/components/system, instead PRIORITIZE using layman's terms or prefer naming with the actual intentions of the code, the GOAL is ease of developer understanding and maintainability.
+
+## Iteration rule
+
+If, while writing the implementation plan, you find a problem that is actually a Design problem
+(not an implementation detail) - e.g. the architecture from Phase 2 doesn't actually support
+something needed - STOP and tell the user clearly, and recommend circling back to Phase 2. Do
+not silently work around a design flaw in the plan.
+
+## Output
+- A comprehensive implementation plan, written to `.workflow/<slug>/03-implement.md`
+
+## Trigger
+```
+$ARGUMENTS = "project name"
+```

package/.opencode/commands/phase-4.md

@@ -1,41 +1,41 @@
----
-description: "Phase 4: Postmortem"
-argument-hint: [project name]
----
-
-## Step 0 — find which project this is for
-
-Before anything else, figure out which project this command applies to:
-
-1. If you were given a project name after the slash (e.g. `/phase-4 my-project`), use it.
-2. Otherwise, look at the subfolders under `.workflow/`:
-   - Exactly one folder → use it. Tell the user which project you picked (e.g. "Working on
-     `my-project`"), so it's never a silent guess.
-   - Two or more folders → ask the user once which project this is for. To make the question
-     useful, show the first line of each project's `00-context.md`, not just the folder name.
-   - No folders → stop and tell the user to run `/kickoff` first. Don't proceed.
-
-# Phase 4: Postmortem
-
-## Purpose
-Reflect on the iteration to improve the next one.
-
-## Prerequisites
-- Phase 3 (Implement) is complete
-
-## Steps
-
-1. **What went well?** — capture successful patterns
-2. **What could be better?** — identify friction and slowdowns
-3. **What will we do differently?** — concrete improvements for next iteration
-4. **Update workflow** — if a process change is needed, update the relevant command files
-
-## Output
-- Postmortem document
-- Action items for next iteration
-- Updated workflow documentation (if needed)
-
-## Trigger
-```
-$ARGUMENTS = "project name"
-```
+---
+description: "Phase 4: Postmortem"
+argument-hint: [project name]
+---
+
+## Step 0 — find which project this is for
+
+Before anything else, figure out which project this command applies to:
+
+1. If you were given a project name after the slash (e.g. `/phase-4 my-project`), use it.
+2. Otherwise, look at the subfolders under `.workflow/`:
+   - Exactly one folder → use it. Tell the user which project you picked (e.g. "Working on
+     `my-project`"), so it's never a silent guess.
+   - Two or more folders → ask the user once which project this is for. To make the question
+     useful, show the first line of each project's `00-context.md`, not just the folder name.
+   - No folders → stop and tell the user to run `/kickoff` first. Don't proceed.
+
+# Phase 4: Postmortem
+
+## Purpose
+Reflect on the iteration to improve the next one.
+
+## Prerequisites
+- Phase 3 (Implement) is complete
+
+## Steps
+
+1. **What went well?** — capture successful patterns
+2. **What could be better?** — identify friction and slowdowns
+3. **What will we do differently?** — concrete improvements for next iteration
+4. **Update workflow** — if a process change is needed, update the relevant command files
+
+## Output
+- Postmortem document
+- Action items for next iteration
+- Updated workflow documentation (if needed)
+
+## Trigger
+```
+$ARGUMENTS = "project name"
+```

package/.opencode/commands/session-transcript.md

@@ -1,71 +1,69 @@
----
-description: "Session Transcript"
-argument-hint: [optional: project name]
----
-
-## Step 0 — find which project this is for
-
-Before anything else, figure out which project this command applies to:
-
-1. If you were given a project name after the slash (e.g. `/session-transcript my-project`), use it.
-2. Otherwise, look at the subfolders under `.workflow/`:
-   - Exactly one folder → use it. Tell the user which project you picked (e.g. "Working on
-     `my-project`"), so it's never a silent guess.
-   - Two or more folders → ask the user once which project this is for. To make the question
-     useful, show the first line of each project's `00-context.md`, not just the folder name.
-   - No folders → fall back to the project root directory name as the project name (this is the
-     one case where no project is in progress yet — a transcript may legitimately exist outside
-     of `.workflow/`).
-
-# Session Transcript
-
-## Purpose
-Record this session's conversation as-is, in chronological order (who said what), as a standalone factual record — separate from the workflow's phase deliverables (which only contain final results, not the discussion that led to them).
-
-## Steps
-
-1. **Scan the project root.** Do NOT create any new folders. Determine the project root directory (where `.git/` or `package.json` or similar marker exists). Save the transcript directly in the project root.
-
-2. **Scan the project root.** Do NOT create any new folders. Determine the project root directory (where `.git/` or `package.json` or similar marker exists). Save the transcript directly in the project root.
-
-3. **Reconstruct this session's conversation in chronological order**, turn by turn, labeled by
-   who said it (`User` / `Agent`). Use the actual wording from the conversation - do not
-   summarize, paraphrase, condense, or skip turns.
-
-4. **Be honest about context limits.** You can only transcribe what's actually present in your
-   current context window for this session. If earlier turns were compacted, truncated, or are
-   otherwise not available to you, say so explicitly at the top of the file (e.g. "Transcript
-   starts partway through the session - earlier turns were not available in context") instead of
-   inventing or guessing what was said.
-
-5. **Check for an existing transcript file.** If `aichat-<slug>.md` already exists from a
-   previous run, do not overwrite it - append this session's transcript below the existing
-   content, under a new dated section, so multiple sessions accumulate in one file.
-
-## Output format
-
-```markdown
-# Session Transcript
-
-## Project: <project-name>
-
-## Session: <date/time if known, otherwise "session N">
-
-### User
-<verbatim text of the turn>
-
-### Agent
-<verbatim text of the turn>
-
-### User
-<verbatim text of the turn>
-
-...
-```
-
-Write the result to `aichat-<slug>.md` in the project root. If no project name was provided, use `aichat.md`.
-
-## Trigger
-```
-$ARGUMENTS = "optional: project name"
-```
+---
+description: "Session Transcript"
+argument-hint: [optional: project name]
+---
+
+## Step 0 — find which project this is for
+
+Before anything else, figure out which project this command applies to:
+
+1. If you were given a project name after the slash (e.g. `/session-transcript my-project`), use it.
+2. Otherwise, look at the subfolders under `.workflow/`:
+   - Exactly one folder → use it. Tell the user which project you picked (e.g. "Working on
+     `my-project`"), so it's never a silent guess.
+   - Two or more folders → ask the user once which project this is for. To make the question
+     useful, show the first line of each project's `00-context.md`, not just the folder name.
+   - No folders → fall back to the project root directory name as the project name (this is the
+     one case where no project is in progress yet — a transcript may legitimately exist outside
+     of `.workflow/`).
+
+# Session Transcript
+
+## Purpose
+Record this session's conversation as-is, in chronological order (who said what), as a standalone factual record — separate from the workflow's phase deliverables (which only contain final results, not the discussion that led to them).
+
+## Steps
+
+1. **Scan the project root.** Do NOT create any new folders. Determine the project root directory (where `.git/` or `package.json` or similar marker exists). Save the transcript directly in the project root.
+
+2. **Reconstruct this session's conversation in chronological order**, turn by turn, labeled by
+   who said it (`User` / `Agent`). Use the actual wording from the conversation - do not
+   summarize, paraphrase, condense, or skip turns.
+
+3. **Be honest about context limits.** You can only transcribe what's actually present in your
+   current context window for this session. If earlier turns were compacted, truncated, or are
+   otherwise not available to you, say so explicitly at the top of the file (e.g. "Transcript
+   starts partway through the session - earlier turns were not available in context") instead of
+   inventing or guessing what was said.
+
+4. **Check for an existing transcript file.** If `aichat-<slug>.md` already exists from a
+   previous run, do not overwrite it - append this session's transcript below the existing
+   content, under a new dated section, so multiple sessions accumulate in one file.
+
+## Output format
+
+```markdown
+# Session Transcript
+
+## Project: <project-name>
+
+## Session: <date/time if known, otherwise "session N">
+
+### User
+<verbatim text of the turn>
+
+### Agent
+<verbatim text of the turn>
+
+### User
+<verbatim text of the turn>
+
+...
+```
+
+Write the result to `aichat-<slug>.md` in the project root. If no project name was provided, use `aichat.md`.
+
+## Trigger
+```
+$ARGUMENTS = "optional: project name"
+```

package/.opencode/plugins/iterative-dev-workflow.mjs

@@ -1,6 +1,9 @@
 // iterative-dev-workflow — OpenCode plugin.
 //
-// Registers slash commands from root commands/ and injects AGENTS.md into system prompt.
+// Injects AGENTS.md into the system prompt on every chat turn. Also attempts to register
+// commands via the config hook as a bonus - but this is NOT the primary way commands get
+// installed (that's the postinstall script, see bin/install-opencode-commands.mjs), since
+// this hook's behavior isn't guaranteed to be honored across all OpenCode versions.
 
 import fs from 'fs';
 import path from 'path';

package/AGENTS.md

@@ -1,48 +1,67 @@
 # AGENTS.md — Iterative Dev Workflow Plugin
 
-This repo is the `@arsxxi/iterative-dev-workflow` plugin for AI coding agents (OpenCode, Claude Code, Codex, Antigravity CLI). It provides structured development workflow commands.
+## What this repo is
 
-## Architecture
+A structured 4-phase iterative development workflow plugin for AI coding agents (Claude Code, OpenCode, Antigravity/Codex, Gemini).
 
-- **Commands**: defined in `commands/*.md` (template body + frontmatter). The `.toml` files are companion metadata. Do NOT edit `.opencode/commands/` or `.agent/workflows/` directly — they are sync targets.
-- **System prompt**: this file (`AGENTS.md`) is injected into the agent's system prompt by the plugin (`iterative-dev-workflow.mjs`). **Hand-curated, not generated** — see Development below.
-- **Plugin entrypoint**: `.opencode/plugins/iterative-dev-workflow.mjs` — dynamically loads command templates from `commands/` and injects `AGENTS.md` on startup.
+## Source of truth
 
-## Development
-
-After editing `commands/*.md` or `skills/workflow-methodology/SKILL.md`, run:
+`commands/*.md` (10 command files) and `skills/workflow-methodology/SKILL.md` are the authoritative sources. All other platform-specific files are generated from these.
 
+**After editing `commands/` or `skills/`, run:**
 ```bash
 bash scripts/sync-platforms.sh
 ```
 
 This syncs to:
-- `.opencode/commands/` — OpenCode command definitions (full `.md` with frontmatter)
-- `.agent/workflows/` — Antigravity workflow definitions (singular path; frontmatter stripped on copy)
-- `.agents/skills/workflow-methodology/SKILL.md` — Antigravity/Codex skill
+- `.opencode/commands/` — OpenCode slash commands (copied verbatim)
+- `.agent/workflows/` — Antigravity/Codex workflows (copied verbatim)
+- `.agents/skills/workflow-methodology/` — Antigravity/Codex skill
+
+**AGENTS.md is hand-curated.** It is intentionally NOT auto-generated. It serves as the OpenCode system-prompt injection file — a different purpose than the consumer-facing plugin payload. Keep the two in sync manually.
+
+## Workflow overview
 
-This script does **NOT** touch `AGENTS.md` (this file) — edit it by hand. The two files serve different purposes and must evolve independently:
+```
+/kickoff
+  └── /phase-1
+        └── /phase-2-step-1
+              └── /phase-2-step-2
+                    └── /phase-2-step-3  (may loop back to step-1)
+                          └── /phase-2-step-4
+                                └── /phase-2-step-5
+                                      └── /phase-3
+                                            └── /phase-4
+```
 
-| File | Purpose | Source of truth |
-|------|---------|-----------------|
-| `AGENTS.md` (this) | Injected into OpenCode system prompt when plugin runs | Hand-curated |
-| `skills/workflow-methodology/SKILL.md` | Plugin payload for consumer projects (workflow content) | Hand-curated |
+## Hard constraints (every phase)
 
-## Output convention
+- **AVOID overengineering.** Prefer simple, low-complexity implementations. Goal: high maintainability.
+- **AVOID jargon.** Use plain language that states actual intent. Any developer should understand names without translation.
+- **Never skip phases.** Design must be approved before implementation begins.
+- **Iterative, not waterfall.** If a problem surfaces in a later phase but belongs to an earlier one (e.g. an Implement-phase bug that's a Design flaw), circle back to that phase. Do not silently work around it.
 
-When used in a **consumer project** (not this repo), each workflow phase writes output to `.workflow/<slug>/` in the consumer's project root:
-- `00-context.md`, `01-analyze.md`, `02-propose.md`, `02-atam.md`, `02-qa.md`, `02-hifi.md`, `02-journey.md`, `03-implement.md`, `04-postmortem.md`
-- `/session-transcript` writes `aichat-<slug>.md` to the consumer project root
+## How project tracking works
 
-## Phase prerequisite chain
+- `/kickoff` creates `.workflow/<slug>/00-context.md` (platform, description, existing services).
+- Every later `/phase-*` command reads that file first — do not assume or hardcode platform/services.
+- Project names are lowercase, hyphenated slugs (e.g. `article-quality-widget`).
+- Session transcripts are written to the **project root** as `aichat-<slug>.md` (not inside `.workflow/`).
+- `/session-transcript` appends to existing transcript files rather than overwriting.
 
-`/kickoff` -> `/phase-1` -> `/phase-2-step-1` -> `/phase-2-step-2` -> `/phase-2-step-3` (may loop back to step 1) -> `/phase-2-step-4` -> `/phase-2-step-5` -> `/phase-3` -> `/phase-4`
+## Phase 2 Step 3 quirk (SENTINEL guard)
 
-Each phase reads `.workflow/<slug>/00-context.md` first to get platform/stack context. Never skip ahead.
+In `/phase-2-step-3`, if the user copy-pastes the Quality Attributes example without modifying it, the warning text itself will appear in their response. The agent should detect this and keep asking for custom attributes. If the user still doesn't modify it, append `SENTINEL` to the final reminder. The agent does NOT proceed to scoring until custom attributes are provided.
 
-## Key constraints
+## Platform quirks
 
-- **AVOID overengineering.** Prefer simple, low-complexity implementations. High maintainability is the goal.
-- **AVOID jargon** in naming. Use plain language that states actual intent.
-- The agent is an assistant — after each phase, it produces results and stops. The user evaluates and decides whether to continue.
-- If an implementation problem is actually a design flaw, circle back to Phase 2. Do not silently patch around design problems.
+- **OpenCode:** Commands land in `.opencode/commands/` (plural). The `opencode.json` references this plugin via `"plugin": ["@arsxxi/iterative-dev-workflow"]`. The install script (`bin/install-opencode-commands.mjs`) copies `commands/` to `~/.config/opencode/commands/` via `postinstall`.
+- **Antigravity/Codex:** Workflows go in `.agent/workflows/` (singular), skills in `.agents/skills/` (plural).
+- **Claude Code:** Uses `.toml` companion files in `commands/` (auto-generated). Hooks at `hooks/claude-codex-hooks.json` load `AGENTS.md` on session start.
+
+## Development setup
+
+```bash
+npm install          # runs postinstall: installs OpenCode commands globally
+bash scripts/sync-platforms.sh   # syncs to all platform targets
+```