agent-context-store 0.2.8 → 0.2.10

package/README.md

@@ -85,60 +85,100 @@ A summary is shown before anything is written, and you can abort with `n`.
 
 ## Step 3: Run Your First Workflow
 
-Once the store is initialized, use `acs` to create artifacts, validate work, hand off between roles, and package context for the next agent. The examples below use task `DEMO-0001` — replace it with your own task ID.
+After setup, each team member opens their AI agent (Cursor or Claude Code) and invokes the matching role skill by name. The skill tells the agent exactly which `acs` commands to run — the human never types `acs` directly.
 
-### Use Case 1 — BA captures requirements and hands off to SA
+> **Skill invocation syntax**
+> - Cursor / Claude Code: `@acs-ba`, `@acs-sa`, `@acs-dev`, `@acs-qa`
 
-The BA agent writes a requirements document, confirms all artifacts are valid, and creates a locked handoff record for the SA agent to pick up.
+The examples below follow a single feature task `DEMO-0001: Login with OTP` through the full BA → SA → Dev → QA lifecycle.
 
+---
+
+### Use Case 1 — BA captures requirements
+
+**Human → Cursor / Claude Code:**
+```
+/acs-ba We need to add OTP-based login. Task ID is DEMO-0001. Title: "Login with OTP".
+```
+
+The `acs-ba` skill activates and the agent internally runs:
 ```bash
-acs roles                                          # see available roles
-acs role explain ba --task DEMO-0001               # show what BA should produce
-acs ba new srs --task DEMO-0001 --title "Login with OTP"  # create the SRS artifact
-acs validate --role ba --task DEMO-0001            # confirm artifacts are complete
-acs handoff create --from ba --to sa --task DEMO-0001     # lock the BA→SA contract
-acs handoff check HOFF-DEMO-0001-BA-SA             # verify the handoff record
-acs package --task DEMO-0001 --role sa             # bundle context for the SA agent
+acs status && acs doctor
+acs ba new srs --task DEMO-0001 --title "Login with OTP"
+acs ba new user-story --task DEMO-0001 --title "Login with OTP User Story"
+acs ba new acceptance-criteria --task DEMO-0001 --title "Login with OTP Acceptance Criteria"
+acs validate --role ba --task DEMO-0001
+acs handoff create --from ba --to sa --task DEMO-0001
+acs package --task DEMO-0001 --role sa
+acs index
 ```
 
-### Use Case 2 — SA produces design artifacts and hands off to Dev
+The agent ends its response with a structured `[HANDOFF: BA → SA | DEMO-0001]` prompt for the SA agent to pick up.
 
-The SA agent reads the BA package, produces the system design and API spec, then hands off a verified package to the Dev agent.
+---
 
+### Use Case 2 — SA produces system design
+
+**Human → Cursor / Claude Code:**
+```
+/acs-sa Pick up DEMO-0001 from BA. Design the OTP login system.
+```
+
+The `acs-sa` skill activates and the agent internally runs:
 ```bash
-acs next --role sa --task DEMO-0001                # see what SA needs to produce
+acs next --role sa --task DEMO-0001
 acs sa new sdd --task DEMO-0001 --title "Login with OTP System Design"
 acs sa new adr --task DEMO-0001 --title "Use Redis for OTP State"
 acs sa new api-design --task DEMO-0001 --title "OTP Login API"
-acs validate --role sa --task DEMO-0001            # confirm design artifacts pass validation
+acs validate --role sa --task DEMO-0001
 acs handoff create --from sa --to dev --task DEMO-0001
-acs package --task DEMO-0001 --role dev            # bundle context for the Dev agent
+acs package --task DEMO-0001 --role dev
+acs index
 ```
 
-### Use Case 3 — Dev implements and hands off to QA
+The agent ends its response with a `[HANDOFF: SA → DEV | DEMO-0001]` prompt.
 
-The Dev agent reads the SA package, records implementation notes, and hands off to QA with a ready-to-test package.
+---
 
+### Use Case 3 — Dev implements the feature
+
+**Human → Cursor / Claude Code:**
+```
+/acs-dev Implement DEMO-0001 based on the SA design. Task ID is DEMO-0001.
+```
+
+The `acs-dev` skill activates and the agent internally runs:
 ```bash
-acs next --role dev --task DEMO-0001               # confirm inputs are available
-acs dev new implementation-note --task DEMO-0001   # record implementation decisions
+acs next --role dev --task DEMO-0001
+acs dev new implementation-note --task DEMO-0001
 acs validate --role dev --task DEMO-0001
 acs handoff create --from dev --to qa --task DEMO-0001
-acs package --task DEMO-0001 --role qa             # bundle context for the QA agent
+acs package --task DEMO-0001 --role qa
+acs index
 ```
 
-### Use Case 4 — QA writes a test plan and closes the loop
+The agent ends its response with a `[HANDOFF: DEV → QA | DEMO-0001]` prompt.
+
+---
 
-The QA agent reads the Dev package and writes a structured test plan to complete the task lifecycle.
+### Use Case 4 — QA validates and closes the task
 
+**Human → Cursor / Claude Code:**
+```
+/acs-qa Write the test plan for DEMO-0001.
+```
+
+The `acs-qa` skill activates and the agent internally runs:
 ```bash
-acs next --role qa --task DEMO-0001                # confirm handoff from Dev is present
+acs next --role qa --task DEMO-0001
 acs qa new test-plan --task DEMO-0001 --title "OTP Login Test Plan"
 acs validate --role qa --task DEMO-0001
-acs handoff list --task DEMO-0001                  # review all handoffs for the task
-acs index                                          # rebuild index.json
+acs handoff list --task DEMO-0001
+acs index
 ```
 
+All four role artifacts and handoff records are now persisted in the store.
+
 ## How Agents Should Use It
 
 Give each agent access to the same project (in-repo mode) or context store repository (dedicated mode) and instruct it to use `acs` for durable handoffs.

package/agent-config/skills/acs-ba/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: acs-ba
-description: ACS Business Analyst role — capture requirements as SRS artifacts and hand off to the SA agent. Use when acting as BA, writing requirements, or starting a new task from scratch.
+description: ACS Business Analyst role — capture requirements as SRS, user story, and acceptance criteria artifacts, then hand off to the SA agent. Use when acting as BA, writing requirements, or starting a new task from scratch.
 ---
 
 # ACS — Business Analyst (BA) Role
@@ -14,13 +14,15 @@ acs doctor
 
 Fix any errors before continuing.
 
-## 2. Create the SRS Artifact
+## 2. Create BA Artifacts
 
 ```bash
 acs ba new srs --task TASK-123 --title "Feature requirements"
+acs ba new user-story --task TASK-123 --title "Feature user story"
+acs ba new acceptance-criteria --task TASK-123 --title "Feature acceptance criteria"
 ```
 
-**Fill every section immediately** — replace all placeholders with real content from the conversation and source files. List consulted files under `source_refs`. Complete the Validation Checklist at the end of the file.
+**Fill every section immediately** — replace all placeholders with real content from the conversation and source files. List consulted files under `source_refs`. Complete the Validation Checklist at the end of each file.
 
 ## 3. Validate
 
@@ -30,7 +32,27 @@ acs validate --role ba --task TASK-123
 
 Do not proceed until validation passes.
 
-## 4. Hand Off to SA
+## 4. Request Approval
+
+Ask the user or responsible stakeholder to review and approve the BA artifacts before handoff.
+
+Do not create the SA handoff until all required BA artifacts are approved:
+
+- SRS
+- User story
+- Acceptance criteria
+
+If approval is granted, update each BA artifact frontmatter so `status: approved` and `approval_status: approved`.
+
+Then re-run validation:
+
+```bash
+acs validate --role ba --task TASK-123
+```
+
+If approval is not granted, capture the requested changes in the artifacts and repeat validation before asking again.
+
+## 5. Hand Off to SA
 
 ```bash
 acs handoff create --from ba --to sa --task TASK-123
@@ -38,17 +60,19 @@ acs package --task TASK-123 --role sa
 acs index
 ```
 
-## 5. Output Handoff Prompt
+## 6. Output Handoff Prompt
 
-End your response with this prompt for the SA agent:
+Only after approval and handoff creation succeed, end your response with this prompt for the SA agent:
 
 ```
 [HANDOFF: BA → SA | TASK-123]
 
-The BA role has completed requirements for TASK-123.
+The BA role has completed and received approval for requirements for TASK-123.
 
 Artifacts ready for you:
 - <path to SRS artifact>
+- <path to user story artifact>
+- <path to acceptance criteria artifact>
 
 Context package: <path printed by acs package>
 
@@ -60,5 +84,5 @@ Your next steps (SA role):
 5. When done, hand off to DEV: acs handoff create --from sa --to dev --task TASK-123
 
 Open questions from BA (resolve before or during design):
-- <list any open questions from the SRS>
+- <list any open questions from the BA artifacts>
 ```

package/agent-config/skills/acs-dev/SKILL.md

@@ -19,13 +19,14 @@ acs handoff check --from sa --to dev --task TASK-123
 acs package --task TASK-123 --role dev
 ```
 
-## 2. Create Implementation Note
+## 2. Create DEV Artifacts
 
 ```bash
 acs dev new implementation-note --task TASK-123
+acs dev new unit-test-note --task TASK-123
 ```
 
-**Fill every section immediately** — document implementation decisions, deviations from the design, and any constraints discovered during development. List consulted files under `source_refs`. Complete the Validation Checklist at the end of the file.
+**Fill every section immediately** — document implementation decisions, deviations from the design, unit test coverage, and any constraints discovered during development. List consulted files under `source_refs`. Complete the Validation Checklist at the end of each file.
 
 ## 3. Validate
 
@@ -35,7 +36,24 @@ acs validate --role dev --task TASK-123
 
 Do not proceed until validation passes.
 
-## 4. Hand Off to QA
+## 4. Mark Ready for Review
+
+Do not create the QA handoff until all required DEV artifacts are ready for review:
+
+- Implementation note
+- Unit test note
+
+Update each DEV artifact frontmatter so `status: ready_for_review`. Keep `approval_status: pending` unless a reviewer explicitly changes it.
+
+Then re-run validation:
+
+```bash
+acs validate --role dev --task TASK-123
+```
+
+If the work is not ready for review, capture the remaining tasks or blockers in the artifacts and repeat validation before handoff.
+
+## 5. Hand Off to QA
 
 ```bash
 acs handoff create --from dev --to qa --task TASK-123
@@ -43,9 +61,9 @@ acs package --task TASK-123 --role qa
 acs index
 ```
 
-## 5. Output Handoff Prompt
+## 6. Output Handoff Prompt
 
-End your response with this prompt for the QA agent:
+Only after the artifacts are marked ready for review and handoff creation succeeds, end your response with this prompt for the QA agent:
 
 ```
 [HANDOFF: DEV → QA | TASK-123]
@@ -54,14 +72,16 @@ The DEV role has completed implementation for TASK-123.
 
 Artifacts ready for you:
 - <path to implementation note>
+- <path to unit test note>
 
 Context package: <path printed by acs package>
 
 Your next steps (QA role):
 1. Read the context package above.
 2. Run: acs role explain qa --task TASK-123
-3. Create your test plan: acs qa new test-plan --task TASK-123 --title "<title>"
+3. Create QA artifacts: acs qa new test-plan --task TASK-123 --title "<title>" and acs qa new qa-signoff --task TASK-123 --title "<title>"
 4. Fill all sections, then validate: acs validate --role qa --task TASK-123
+5. After approval, mark QA artifacts approved and hand off to SA: acs handoff create --from qa --to sa --task TASK-123
 
 Open questions from DEV (resolve before or during testing):
 - <list any open questions from the implementation note>

package/agent-config/skills/acs-qa/SKILL.md

@@ -19,34 +19,70 @@ acs handoff check --from dev --to qa --task TASK-123
 acs package --task TASK-123 --role qa
 ```
 
-## 2. Create Test Plan
+## 2. Create QA Artifacts
 
 ```bash
 acs qa new test-plan --task TASK-123 --title "Feature test plan"
+acs qa new qa-signoff --task TASK-123 --title "Feature QA signoff"
 ```
 
-**Fill every section immediately** — document test scope, test cases, acceptance criteria, and any risks. List consulted files under `source_refs`. Complete the Validation Checklist at the end of the file.
+**Fill every section immediately** — document test scope, test cases, acceptance criteria, signoff decision, and any risks. List consulted files under `source_refs`. Complete the Validation Checklist at the end of each file.
 
 ## 3. Validate
 
 ```bash
 acs validate --role qa --task TASK-123
+```
+
+Do not proceed until validation passes.
+
+## 4. Request Approval
+
+Ask the user or responsible stakeholder to review and approve the QA artifacts before handoff.
+
+Do not create the SA handoff until all required QA artifacts are approved:
+
+- Test plan
+- QA signoff
+
+If approval is granted, update each QA artifact frontmatter so `status: approved` and `approval_status: approved`.
+
+Then re-run validation:
+
+```bash
+acs validate --role qa --task TASK-123
+```
+
+If approval is not granted, capture the requested changes in the artifacts and repeat validation before asking again.
+
+## 5. Hand Off to SA
+
+```bash
+acs handoff create --from qa --to sa --task TASK-123
+acs package --task TASK-123 --role sa
 acs index
 ```
 
-## 4. Output Completion Report
+## 6. Output Handoff Prompt
 
-QA is the final role in the workflow. End your response with a completion summary:
+Only after approval and handoff creation succeed, end your response with this prompt for the SA agent:
 
 ```
-[COMPLETE: QA | TASK-123]
+[HANDOFF: QA → SA | TASK-123]
 
-QA has completed the test plan for TASK-123.
+The QA role has completed and received approval for QA validation for TASK-123.
 
-Artifacts produced:
+Artifacts ready for you:
 - <path to test plan>
+- <path to QA signoff>
+
+Context package: <path printed by acs package>
 
-Full artifact index: run `acs index` to view all artifacts and handoffs for this task.
+Your next steps (SA role):
+1. Read the context package above.
+2. Run: acs role explain sa --task TASK-123
+3. Create the release readiness report: acs sa new release-readiness-report --task TASK-123 --title "<title>"
+4. Fill all sections, then validate: acs validate --role sa --task TASK-123
 
 Outstanding issues or risks:
 - <list any issues found during QA, or "None">

package/agent-config/skills/acs-sa/SKILL.md

@@ -21,7 +21,7 @@ acs package --task TASK-123 --role sa
 
 ## 2. Create SA Artifacts
 
-Create one or more of the following based on the task scope:
+Create the required SA artifacts before handing off to DEV:
 
 ```bash
 acs sa new sdd --task TASK-123 --title "Feature system design"
@@ -39,7 +39,27 @@ acs validate --role sa --task TASK-123
 
 Do not proceed until validation passes.
 
-## 4. Hand Off to DEV
+## 4. Request Approval
+
+Ask the user or responsible stakeholder to review and approve the SA design artifacts before handoff.
+
+Do not create the DEV handoff until all required design artifacts are approved:
+
+- SDD
+- ADR
+- API design
+
+If approval is granted, update each SA artifact frontmatter so `status: approved` and `approval_status: approved`.
+
+Then re-run validation:
+
+```bash
+acs validate --role sa --task TASK-123
+```
+
+If approval is not granted, capture the requested changes in the artifacts and repeat validation before asking again.
+
+## 5. Hand Off to DEV
 
 ```bash
 acs handoff create --from sa --to dev --task TASK-123
@@ -47,14 +67,14 @@ acs package --task TASK-123 --role dev
 acs index
 ```
 
-## 5. Output Handoff Prompt
+## 6. Output Handoff Prompt
 
-End your response with this prompt for the DEV agent:
+Only after approval and handoff creation succeed, end your response with this prompt for the DEV agent:
 
 ```
 [HANDOFF: SA → DEV | TASK-123]
 
-The SA role has completed the system design for TASK-123.
+The SA role has completed and received approval for the system design for TASK-123.
 
 Artifacts ready for you:
 - <paths to SDD / ADR / API design artifacts>
@@ -64,9 +84,9 @@ Context package: <path printed by acs package>
 Your next steps (DEV role):
 1. Read the context package above.
 2. Run: acs role explain dev --task TASK-123
-3. Create your implementation note: acs dev new implementation-note --task TASK-123
+3. Create implementation artifacts: acs dev new implementation-note --task TASK-123 and acs dev new unit-test-note --task TASK-123
 4. Fill all sections, then validate: acs validate --role dev --task TASK-123
-5. When done, hand off to QA: acs handoff create --from dev --to qa --task TASK-123
+5. Mark DEV artifacts `status: ready_for_review`, re-validate, then hand off to QA: acs handoff create --from dev --to qa --task TASK-123
 
 Open questions from SA (resolve before or during implementation):
 - <list any open questions from the design artifacts>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-context-store",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "acs CLI for Agent Context Store Toolkit.",
   "type": "module",
   "license": "MIT",
@@ -23,7 +23,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.4.2",
-    "agent-context-store-core": "0.2.8"
+    "agent-context-store-core": "0.2.10"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json"