@arsxxi/iterative-dev-workflow 1.0.1 → 1.0.2

package/README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="assets/yamadaaa.png">
-    <img src="assets/yamadaaa.png" width="220" alt="Iterative Dev Workflow">
+    <img src="assets/yamadaaa.png" width="350" alt="Iterative Dev Workflow">
   </picture>
 </p>
 
@@ -11,9 +11,6 @@
   <em>Structure your AI agent's development process.</em>
 </p>
 
-<p align="center">
-  <img src="https://img.shields.io/badge/license-MIT-111111?style=flat-square" alt="MIT license">
-</p>
 
 ---
 
@@ -84,14 +81,27 @@ codex plugin add iterative-dev-workflow@arsxxi-iterative-dev-workflow
 npm install -g @arsxxi/iterative-dev-workflow
 ```
 
-Then add to your `opencode.json`:
+On install, a `postinstall` script copies the commands into `~/.config/opencode/commands/`
+automatically. Restart OpenCode and type `/` to see them.
+
+If commands still don't show up (some package managers or environments skip lifecycle scripts,
+or your OpenCode version doesn't pick them up automatically), run the installer manually:
+
+```bash
+npx --package=@arsxxi/iterative-dev-workflow iterative-dev-workflow-install
+```
+
+Or, as a guaranteed last resort, copy the `commands/` folder from this repo directly into
+`~/.config/opencode/commands/` (global) or `.opencode/commands/` inside your project yourself -
+these are plain markdown files, no build step required.
+
+Then add to your `opencode.json` (this enables the AGENTS.md system-prompt injection feature,
+separate from command registration):
 
 ```json
 { "plugin": ["@arsxxi/iterative-dev-workflow"] }
 ```
 
-Slash commands are auto-installed to `~/.config/opencode/commands/` on first run.
-
 ### Antigravity CLI
 
 ```bash
@@ -184,6 +194,13 @@ Use a short, lowercase identifier with hyphens (e.g. `user-auth`, `article-quali
 
 Step 4 creates a System Context Diagram — shows how the solution fits within the whole app. Step 5 creates a User Journey Diagram — shows how the user interacts with the system.
 
+## Acknowledgments
+
+The Analyze → Design → Implement → Post-Mortem methodology, including the ATAM/SQALE
+assessment framework and phase-gating prompts, was designed by **Hanzz**
+([@haniladjamba](https://github.com/haniladjamba)). Implementation, cross-platform tooling,
+and CI were built by [Arsxxi](https://github.com/Arsxxi).
+
 ## License
 
 [MIT](LICENSE)

package/bin/install-opencode-commands.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// Writes this package's commands/*.md into OpenCode's global commands directory
+// (~/.config/opencode/commands/) so slash commands work regardless of whether
+// OpenCode's internal plugin "config" hook is supported in the installed version.
+//
+// Run automatically via the "postinstall" npm script. If that doesn't fire in your
+// environment (some package managers skip lifecycle scripts by default), run this
+// manually:
+//   npx --package=@arsxxi/iterative-dev-workflow iterative-dev-workflow-install
+// or just copy the commands/ folder from this package into your OpenCode commands dir
+// yourself - see README.md.
+
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.join(__dirname, "..");
+const sourceDir = path.join(packageRoot, "commands");
+
+const globalTarget = path.join(os.homedir(), ".config", "opencode", "commands");
+
+function copyCommands(targetDir) {
+  fs.mkdirSync(targetDir, { recursive: true });
+  const files = fs.readdirSync(sourceDir).filter((f) => f.endsWith(".md"));
+  for (const f of files) {
+    fs.copyFileSync(path.join(sourceDir, f), path.join(targetDir, f));
+  }
+  return files.length;
+}
+
+try {
+  const count = copyCommands(globalTarget);
+  console.log(
+    `[iterative-dev-workflow] Installed ${count} OpenCode commands to ${globalTarget}`
+  );
+  console.log(
+    "[iterative-dev-workflow] Restart OpenCode, then type / to see them (kickoff, phase-1, ...)."
+  );
+} catch (err) {
+  console.warn(
+    "[iterative-dev-workflow] Could not auto-install OpenCode commands:",
+    err.message
+  );
+  console.warn(
+    `[iterative-dev-workflow] Manual fix: copy the commands/ folder from this package into ${globalTarget}`
+  );
+}

package/commands/kickoff.md

@@ -1,90 +1,90 @@
----
-description: "Kickoff"
-argument-hint: [optional: project name and what we're building]
----
-
-## Step 0 - figure out what we're building (do this FIRST, before anything else)
-
-Look at what was passed in: `$ARGUMENTS`
-
-- If it already clearly states a project name, a real description of what to build, AND the
-  platform/stack (e.g. "React Native non-Expo", "Python backend service", "LLM agent pipeline"),
-  confirm your understanding back to me in one or two sentences and proceed to the section below.
-- If any of those three are missing or vague, **stop and ask me**:
-  1. What are we building? (be as comprehensive as you want me to be - the more detail, the
-     better Phase 1 will be)
-  2. What platform/stack is this for? (e.g. mobile app - React Native/Expo/native, backend
-     service, LLM/agent pipeline, web frontend, CLI tool, etc. - this changes what Phase 1's
-     library/service analysis actually looks like)
-  3. What short project name should identify it? (used for the `.workflow/<slug>/` folder, e.g.
-     `article-quality-widget`)
-
-  Do not guess or invent a feature, and do not assume a default platform/stack (do not assume
-  React Native or anything else) to analyze. Do not proceed past this point until I've answered.
-
-Also ask (can be part of the same question round): what services/infra already exist in this
-project that Phase 1 should treat as "Existing Services" (e.g. a specific backend, database,
-auth provider, third-party APIs already wired up) - versus what's clearly new and would count as
-"Proposed Services". If I say I'm not sure or there's nothing existing yet, that's a valid
-answer - don't invent a services list.
-
-Once you know the platform/stack and existing services, use them consistently for the rest of
-this workflow (Phase 1's library/package questions, Phase 2's architecture diagrams, etc. should
-all be framed for this specific project, not a generic or assumed one).
-
-## Step 1 - once we know what we're building
-
-Here is the workflow we use for every feature, regardless of platform/stack:
-
-- **Phase 1: Analyze** - requirements, libraries/packages, Existing vs. Proposed services, 5
-  candidate development paths, ATAM + SQALE, final timeline.
-- **Phase 2: Design** - Solution Proposal (low-fidelity, divergent) -> ATAM -> Quality
-  Attribute Assessment (weighted scoring, may loop back to the proposal bucket) -> High-Fidelity
-  Design (System Context + User Flow diagrams in Mermaid.js).
-- **Phase 3: Implement** - build it, following the High-Fidelity Design.
-- **Phase 4: Post-Mortem** - retrospective.
-
-This is an **iterative model, not waterfall**: if a problem surfaces in a later phase but
-actually belongs to an earlier phase (e.g. an Implement-phase bug that's really a Design flaw),
-we circle back to that earlier phase to fix it there rather than patching around it downstream.
-
-I want you to do a deep, meticulous, extensive analysis of this workflow before we touch Phase 1:
-
-1. Evaluate how it aligns with professional industry practice (e.g. where it maps to standard
-   models like Double Diamond, Set-Based Design, ATAM, SQALE - and where it deliberately departs
-   from them, and why that's reasonable for a project this size).
-2. Flag any real gaps or risks in the workflow itself, applied to what we're building
-   specifically - not generic commentary.
-3. Confirm you understand your role: you're my assistant through this, not an autopilot. After
-   each phase/step, you produce results and stop - I evaluate them and decide whether we move
-   on, adjust, or loop back. You never advance phases on your own.
-
-## Step 2 - set up tracking
-
-Once I've confirmed the analysis, create `.workflow/<slug>/` in this project (using the project name
-we settled on in Step 0) and write `.workflow/<slug>/00-context.md` containing:
-
-- Platform/stack
-- What we're building (the description from Step 0)
-- Existing Services (as I described them, or "none identified yet" if I said so)
-
-Every later `/phase-*` command for this project should read this file first and use it instead
-of assuming or hardcoding a platform or services list.
-
-## Hard constraints (apply for the entire workflow, every phase)
-
-- AVOID overengineering. PREFER simple, low-complexity implementations. GOAL: high
-  maintainability.
-- AVOID jargon when naming components/systems/functions - prefer plain language that states the
-  actual intent, so any developer can understand it without translation.
-
-## Output
-
-Give me your analysis of the workflow in chat (no need to write this one to a file - it's a
-one-time discussion, not a phase deliverable). End by telling me you're ready for
-`/phase-1` when I am.
-
-## Trigger
-```
-$ARGUMENTS = "optional: project name and what we're building"
-```
+---
+description: "Kickoff"
+argument-hint: [optional: project name and what we're building]
+---
+
+## Step 0 - figure out what we're building (do this FIRST, before anything else)
+
+Look at what was passed in: `$ARGUMENTS`
+
+- If it already clearly states a project name, a real description of what to build, AND the
+  platform/stack (e.g. "React Native non-Expo", "Python backend service", "LLM agent pipeline"),
+  confirm your understanding back to me in one or two sentences and proceed to the section below.
+- If any of those three are missing or vague, **stop and ask me**:
+  1. What are we building? (be as comprehensive as you want me to be - the more detail, the
+     better Phase 1 will be)
+  2. What platform/stack is this for? (e.g. mobile app - React Native/Expo/native, backend
+     service, LLM/agent pipeline, web frontend, CLI tool, etc. - this changes what Phase 1's
+     library/service analysis actually looks like)
+  3. What short project name should identify it? (used for the `.workflow/<slug>/` folder, e.g.
+     `article-quality-widget`)
+
+  Do not guess or invent a feature, and do not assume a default platform/stack (do not assume
+  React Native or anything else) to analyze. Do not proceed past this point until I've answered.
+
+Also ask (can be part of the same question round): what services/infra already exist in this
+project that Phase 1 should treat as "Existing Services" (e.g. a specific backend, database,
+auth provider, third-party APIs already wired up) - versus what's clearly new and would count as
+"Proposed Services". If I say I'm not sure or there's nothing existing yet, that's a valid
+answer - don't invent a services list.
+
+Once you know the platform/stack and existing services, use them consistently for the rest of
+this workflow (Phase 1's library/package questions, Phase 2's architecture diagrams, etc. should
+all be framed for this specific project, not a generic or assumed one).
+
+## Step 1 - once we know what we're building
+
+Here is the workflow we use for every feature, regardless of platform/stack:
+
+- **Phase 1: Analyze** - requirements, libraries/packages, Existing vs. Proposed services, 5
+  candidate development paths, ATAM + SQALE, final timeline.
+- **Phase 2: Design** - Solution Proposal (low-fidelity, divergent) -> ATAM -> Quality
+  Attribute Assessment (weighted scoring, may loop back to the proposal bucket) -> High-Fidelity
+  Design (System Context + User Flow diagrams in Mermaid.js).
+- **Phase 3: Implement** - build it, following the High-Fidelity Design.
+- **Phase 4: Post-Mortem** - retrospective.
+
+This is an **iterative model, not waterfall**: if a problem surfaces in a later phase but
+actually belongs to an earlier phase (e.g. an Implement-phase bug that's really a Design flaw),
+we circle back to that earlier phase to fix it there rather than patching around it downstream.
+
+I want you to do a deep, meticulous, extensive analysis of this workflow before we touch Phase 1:
+
+1. Evaluate how it aligns with professional industry practice (e.g. where it maps to standard
+   models like Double Diamond, Set-Based Design, ATAM, SQALE - and where it deliberately departs
+   from them, and why that's reasonable for a project this size).
+2. Flag any real gaps or risks in the workflow itself, applied to what we're building
+   specifically - not generic commentary.
+3. Confirm you understand your role: you're my assistant through this, not an autopilot. After
+   each phase/step, you produce results and stop - I evaluate them and decide whether we move
+   on, adjust, or loop back. You never advance phases on your own.
+
+## Step 2 - set up tracking
+
+Once I've confirmed the analysis, create `.workflow/<slug>/` in this project (using the project name
+we settled on in Step 0) and write `.workflow/<slug>/00-context.md` containing:
+
+- Platform/stack
+- What we're building (the description from Step 0)
+- Existing Services (as I described them, or "none identified yet" if I said so)
+
+Every later `/phase-*` command for this project should read this file first and use it instead
+of assuming or hardcoding a platform or services list.
+
+## Hard constraints (apply for the entire workflow, every phase)
+
+- AVOID overengineering. PREFER simple, low-complexity implementations. GOAL: high
+  maintainability.
+- AVOID jargon when naming components/systems/functions - prefer plain language that states the
+  actual intent, so any developer can understand it without translation.
+
+## Output
+
+Give me your analysis of the workflow in chat (no need to write this one to a file - it's a
+one-time discussion, not a phase deliverable). End by telling me you're ready for
+`/phase-1` when I am.
+
+## Trigger
+```
+$ARGUMENTS = "optional: project name and what we're building"
+```

package/commands/kickoff.toml

@@ -1,2 +1,2 @@
-description = "Kickoff: introduce the 4-phase iterative workflow, ask what we're building, then analyze the workflow itself before starting Phase 1"
-prompt = "Run the kickoff workflow. Step 0: figure out what we're building — ask about platform/stack, feature description, and project name. Step 1: analyze the workflow itself. Step 2: set up .workflow/<slug>/00-context.md. Use $ARGUMENTS as initial input. Reference: $ARGUMENTS"
+description = "Kickoff: introduce the 4-phase iterative workflow, ask what we're building, then analyze the workflow itself before starting Phase 1"
+prompt = "Run the kickoff workflow. Step 0: figure out what we're building — ask about platform/stack, feature description, and project name. Step 1: analyze the workflow itself. Step 2: set up .workflow/<slug>/00-context.md. Use $ARGUMENTS as initial input. Reference: $ARGUMENTS"

package/commands/phase-1.md

@@ -1,43 +1,47 @@
----
-description: "Phase 1: Analyze"
-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-1 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 1: Analyze
-
-## Purpose
-Understand the task deeply before writing any code.
-
-## Steps
-
-1. **Read the task** — understand what the user is asking for
-2. **Explore the codebase** — understand existing patterns, structure, and constraints
-3. **Identify gaps** — what information is missing? What needs clarification?
-4. **Ask questions if needed** — use the ask-questions-if-underspecified skill when requirements are unclear
-
-## Output
-- A clear summary of what needs to be built
-- Identified constraints and context
-- List of open questions (if any)
-
-## When to escalate
-- Requirements are ambiguous or contradictory
-- Task involves security-critical or irreversible changes
-- Scope is too large for a single iteration
-
-## Trigger
-```
-$ARGUMENTS = "project name"
-```
+---
+description: "Phase 1: Analyze"
+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-1 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 1: Analyze
+
+## Purpose
+Analyze the requirements with the goal to propose a development timeline and plan.
+
+## Steps
+
+1. **Gather requirements** — do the usual analysis to gather requirements for what we wanted to build: $ARGUMENTS
+2. **Identify libraries / npm packages** — determine what libraries / npm packages will be used
+3. **Categorize services** — separate into two categories: Existing Services (the list of services currently available for the project: ask the user) and Proposed Services (the list of services needed to be added into the project)
+4. **Brainstorm development paths** — brainstorm 5 various paths of development
+5. **Perform ATAM** — perform an ATAM analysis of those paths of development
+6. **Perform SQALE** — perform a SQALE analysis of those paths of development
+7. **Write final output** — write the Development Timeline and explanation of chosen plan/solution
+
+## Output
+Write to `.workflow/<slug>/phase-1.md`:
+- Development Timeline
+- Explanation of chosen plan/solution
+- Libraries / npm packages to be used
+- Existing Services and Proposed Services breakdown
+
+## Constraints
+- AVOID overengineering, PREFER simple, low-complexity implementations with the GOAL of high maintainability
+- AVOID jargons when naming components/systems, instead PRIORITIZE using layman's terms or prefer naming with the actual intentions of the components/systems, the GOAL is ease of developer understanding and maintainability
+
+## Trigger
+```
+$ARGUMENTS = "project name"
+```

package/commands/phase-2-step-1.md

@@ -1,37 +1,39 @@
----
-description: "Phase 2 Step 1: Solution Proposal"
-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-1 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 1: Solution Proposal
-
-## Purpose
-Create a minimum of 5 designs that we can use to solve our problem, according to the previous instruction about this step.
-
-## Steps
-
-1. **Recall the previous instruction** about Step 1: Solution Proposal
-2. **Analyze industry standard** — do a deep dive, extensive and meticulous analysis on how industry standard conducts this step
-3. **Create minimum 5 designs** that we can use to solve our problem
-4. **Proceed to execute Step 1**
-
-## Output
-- Analysis of how industry standard conducts this step
-- Minimum 5 design candidates
-
-## Trigger
-```
-$ARGUMENTS = "project name"
-```
+---
+description: "Phase 2 Step 1: Solution Proposal"
+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-1 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 1: Solution Proposal
+
+## Purpose
+Create a minimum of 5 design proposals for the chosen development path from Phase 1.
+
+## Prerequisites
+- Phase 1 output (`.workflow/<slug>/phase-1.md`) must exist and be non-empty. If it's missing or empty, do not proceed — remind the user.
+
+## Steps
+
+1. **Read Phase 1 output** — read `.workflow/<slug>/phase-1.md` to understand the chosen development path and its reasoning.
+2. **Analyze industry standard** — do a deep dive, extensive and meticulous analysis on how industry standard conducts solution proposal
+3. **Create minimum 5 design proposals** — create design proposals for the chosen development path from Phase 1. Each proposal should detail: Architecture, UI/UX approach, Data Model, and trade-offs at this design level.
+
+## Output
+- Industry standard analysis
+- Minimum 5 design proposals for the chosen Phase 1 path
+
+## Trigger
+```
+$ARGUMENTS = "project name"
+```

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

@@ -1,39 +1,39 @@
----
-description: "Phase 2 Step 2: ATAM"
-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-2 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 2: ATAM
-
-## Purpose
-Assess each design using ATAM. Our goal is to identify trade-offs and sensitivity points on each design.
-
-## Steps
-
-1. **Check for the previous result** from the previous step. If it's empty or not generated due to certain reason, DO NOT PROCEED TO EXECUTE THIS STEP. Don't forget to remind the user if this happened.
-2. **Analyze all of our designs** — do a deep dive, extensive and meticulous analysis on all of our designs
-3. **Proceed to execute Step 2: ATAM**
-
-## Output
-- Trade-offs identified for each design
-- Sensitivity points identified for each design
-
-## Error handling
-If any step contains an error regarding user prompts, INFORM THE USER and DO NOT CONTINUE.
-
-## Trigger
-```
-$ARGUMENTS = "project name"
-```
+---
+description: "Phase 2 Step 2: ATAM"
+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-2 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 2: ATAM
+
+## Purpose
+Assess each design using ATAM. Our goal is to identify trade-offs and sensitivity points on each design.
+
+## Steps
+
+1. **Check for the previous result** from the previous step. If it's empty or not generated due to certain reason, DO NOT PROCEED TO EXECUTE THIS STEP. Don't forget to remind the user if this happened.
+2. **Analyze all of our designs** — do a deep dive, extensive and meticulous analysis on all of our designs
+3. **Proceed to execute Step 2: ATAM**
+
+## Output
+- Trade-offs identified for each design
+- Sensitivity points identified for each design
+
+## Error handling
+If any step contains an error regarding user prompts, INFORM THE USER and DO NOT CONTINUE.
+
+## Trigger
+```
+$ARGUMENTS = "project name"
+```