agent-context-store 0.2.9 → 0.2.11

package/README.md

@@ -6,6 +6,8 @@ Agent Context Store (`acs`) is a Git-backed, schema-validated handoff toolkit th
 
 Each role agent writes schema-validated documents — SRS, design docs, ADRs, API specs, test plans — with structured frontmatter into a Git-tracked store. A validated handoff record acts as the contract between agents; the receiving agent packages and reads it before starting work. Works with Cursor, Claude Code, Codex, CI pipelines, and any custom agent runtime.
 
+`acs` is built on the same handoff principles formalized by the [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/handoffs/), the [Microsoft Agent Framework](https://learn.microsoft.com/en-us/agent-framework/workflows/orchestrations/handoff) handoff orchestration, and Google's [Agent2Agent (A2A) protocol](https://github.com/a2aproject/A2A) — applied to the SDLC roles BA, SA, Dev, QA, and persisted to Git so handoffs survive across runtimes, sessions, and CI.
+
 ## Architecture
 
 ```mermaid
@@ -83,6 +85,21 @@ Run `acs init` in your project directory. When stdin is a terminal, an interacti
 
 A summary is shown before anything is written, and you can abort with `n`.
 
+Pass `--mode` to skip the wizard entirely:
+
+```bash
+acs init                        # wizard (TTY only)
+acs init --mode in-repo         # silent, creates .acs/ in current dir
+acs init --mode local           # silent, stores in OS user-data dir
+acs init --mode dedicated .     # silent, current dir is the store root
+```
+
+| Mode | Where context is stored | Best for |
+|------|------------------------|----------|
+| **in-repo** _(default)_ | `.acs/` inside your project | Most projects — context stays with code |
+| **local** | OS user-data dir | Personal workflows, no repo changes |
+| **dedicated** | This folder IS the store root | Multi-project teams, CI governance |
+
 ## Step 3: Run Your First Workflow
 
 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.
@@ -179,46 +196,9 @@ 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.
-
-Suggested agent instruction:
-
-```text
-Use Agent Context Store for durable project context.
-Before creating or handing off work, run acs status and acs validate.
-Use acs roles, acs role explain, and acs next to follow the configured workflow.
-Create task artifacts with acs new or acs <role> new.
-Create role handoffs with acs handoff create.
-Generate the next role package with acs package.
-Commit context store changes to the configured Git repository.
-```
-
 ## Context Store Layout
 
-### In-repo mode (default)
-
-```text
-.acs/
-  config.yaml
-  acs.yaml
-  index.json
-  audit/
-  artifacts/
-    <artifact-type>/
-  handoffs/
-  summaries/
-  packages/
-  roles/
-  artifact-types/
-  workflows/
-  schemas/
-  templates/
-  docs/
-```
-
-### Dedicated mode
+The store root is `.acs/` in **in-repo** mode and `<store-root>/` in **dedicated** mode. Both use the same structure:
 
 ```text
 <store-root>/
@@ -227,6 +207,7 @@ Commit context store changes to the configured Git repository.
   index.json
   audit/
   artifacts/
+    <artifact-type>/
   handoffs/
   summaries/
   packages/
@@ -238,37 +219,33 @@ Commit context store changes to the configured Git repository.
   docs/
 ```
 
-Important outputs:
-
 - `artifacts/`: durable SDLC artifacts such as requirements, designs, ADRs, API notes, and test plans.
 - `handoffs/`: explicit role-to-role handoff records.
 - `packages/`: role-specific context bundles for the next agent.
 - `index.json`: generated artifact and handoff index.
 - `audit/`: local audit log for CLI-created changes.
 
-In **in-repo mode** all paths above are inside `.acs/`.
-
 ## Commands
 
-| Command              | What it does                                                                                            | Example                                                      |
-| -------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
-| `acs --version`      | Prints the installed CLI version.                                                                       | `acs --version`                                              |
-| `acs init`           | Initializes the context store. Runs an interactive wizard on a TTY; pass `--mode` to skip it.          | `acs init`, `acs init --mode local`                         |
-| `acs status`         | Shows current mode, store path, initialized state, and artifact/handoff counts.                         | `acs status`                                                 |
-| `acs install-skills` | Installs agent-specific skill and instruction files for Cursor, Claude, Codex, or all supported agents. | `acs install-skills --agent cursor`                          |
-| `acs roles`          | Lists configured role profiles.                                                                         | `acs roles`                                                  |
-| `acs role explain`   | Explains what a role can create/read and suggests task commands.                                        | `acs role explain dev --task TASK-123`                       |
-| `acs next`           | Shows missing inputs, suggested outputs, and next workflow commands.                                    | `acs next --role sa --task TASK-123`                         |
-| `acs new`            | Creates a configured SDLC artifact.                                                                     | `acs ba new srs --task TASK-123`                             |
-| `acs validate`       | Validates the context store structure, artifact metadata, schemas, and handoff records.                 | `acs validate --role dev --task TASK-123`                    |
-| `acs handoff create` | Creates a role-to-role handoff record for a task.                                                       | `acs handoff create --from sa --to dev --task TASK-123`      |
-| `acs handoff check`  | Validates a specific handoff before another agent relies on it.                                         | `acs handoff check HOFF-TASK-123-SA-DEV`                     |
-| `acs handoff list`   | Lists handoff records, optionally filtered by task or role.                                             | `acs handoff list --task TASK-123`                           |
-| `acs package`        | Builds a role-specific context package for the next agent or automation step.                           | `acs package --task TASK-123 --role dev`                     |
-| `acs index`          | Rebuilds `index.json` from artifacts and handoffs.                                                      | `acs index`                                                  |
-| `acs doctor`         | Runs the same validation checks as `acs validate` for quick health checks.                              | `acs doctor`                                                 |
-
-### Command - Reference
+| Command              | What it does                                                                                            |
+| -------------------- | ------------------------------------------------------------------------------------------------------- |
+| `acs --version`      | Prints the installed CLI version.                                                                       |
+| `acs init`           | Initializes the context store. Runs an interactive wizard on a TTY; pass `--mode` to skip it.          |
+| `acs status`         | Shows current mode, store path, initialized state, and artifact/handoff counts.                         |
+| `acs install-skills` | Installs agent-specific skill and instruction files for Cursor, Claude, Codex, or all supported agents. |
+| `acs roles`          | Lists configured role profiles (`ba`, `sa`, `dev`, `qa`).                                              |
+| `acs role explain`   | Explains what a role can create/read and suggests task commands.                                        |
+| `acs next`           | Shows missing inputs, suggested outputs, and next workflow commands.                                    |
+| `acs new`            | Creates a configured SDLC artifact.                                                                     |
+| `acs validate`       | Validates the context store structure, artifact metadata, schemas, and handoff records.                 |
+| `acs handoff create` | Creates a role-to-role handoff record for a task.                                                       |
+| `acs handoff check`  | Validates a specific handoff before another agent relies on it.                                         |
+| `acs handoff list`   | Lists handoff records, optionally filtered by task or role.                                             |
+| `acs package`        | Builds a role-specific context package for the next agent or automation step.                           |
+| `acs index`          | Rebuilds `index.json` from artifacts and handoffs.                                                      |
+| `acs doctor`         | Runs the same validation checks as `acs validate` for quick health checks.                              |
+
+### Full syntax
 
 ```bash
 acs --version
@@ -291,35 +268,6 @@ acs index
 acs doctor
 ```
 
-Common roles:
-
-- `ba`
-- `sa`
-- `dev`
-- `developer`
-- `qa`
-- `reviewer`
-
-
-### Command - init
-
-Pass `--mode` to skip the wizard entirely:
-
-```bash
-acs init                        # wizard (TTY only)
-acs init --mode in-repo         # silent, creates .acs/ in current dir
-acs init --mode local           # silent, stores in OS user-data dir
-acs init --mode dedicated .     # silent, current dir is the store root
-```
-
-`acs` supports three storage modes:
-
-| Mode | Where context is stored | Best for |
-|------|------------------------|----------|
-| **in-repo** _(default)_ | `.acs/` inside your project | Most projects — context stays with code |
-| **local** | OS user-data dir | Personal workflows, no repo changes |
-| **dedicated** | This folder IS the store root | Multi-project teams, CI governance |
-
 ### Command - install-skills
 
 The wizard offers to install skill files during `acs init`. You can also run this separately at any time:
@@ -342,6 +290,33 @@ acs install-skills --agent all --path /path/to/repo
 
 Skill files are always replaced with the bundled version. If `AGENTS.md` or `CLAUDE.md` already exists, the installer appends to it.
 
+
+## Aligned with Industry Handoff Standards
+
+`acs` adopts the same handoff vocabulary used by the major agent frameworks — typed handoff records, dynamic role-to-role routing, full task ownership transfer, capability advertisement, and durable checkpointing — and grounds them in a Git-tracked store so the handoff itself becomes an auditable, reviewable artifact rather than an in-memory tool call.
+
+| Concept | Industry definition | `acs` equivalent |
+|---------|--------------------|------------------|
+| **Typed handoff contract** | OpenAI's `handoff()` with `input_type` schema, `handoff_description`, and `on_handoff` callback validates the data passed between agents. [[#1]](#references) | `acs handoff create --from <ROLE> --to <ROLE> --task <TASK_ID>` writes a YAML record validated against a JSON schema; `acs handoff check` is the receiver-side guard equivalent to `on_handoff` validation. |
+| **Context filtering on handoff** | OpenAI `input_filter` and Microsoft's `HandoffAgentExecutor` strip handoff tool calls before forwarding to the next agent. [[#1]](#references) [[#2]](#references) | `acs package --task <TASK_ID> --role <ROLE>` builds a role-scoped context bundle so the receiving agent reads only what is relevant to its job. |
+| **Full task ownership transfer** | Microsoft Agent Framework: "the agent receiving the handoff takes full ownership of the task" (vs. agent-as-tools, where control returns). [[#2]](#references) | BA → SA → Dev → QA each take complete ownership of the task in their phase; control does not return to the previous role. |
+| **Mesh topology, no central orchestrator** | Microsoft: agents are connected directly; each decides when to hand off. [[#2]](#references) | No orchestrator process — each role agent independently decides when its artifacts are complete and issues a handoff. The store is the shared substrate. |
+| **Dynamic routing rules** | Microsoft `HandoffBuilder.add_handoff(...)` / `WithHandoffs(...)` declares which agents may route to which. [[#2]](#references) | `workflows/` and `roles/` in the store define the legal BA→SA→Dev→QA edges; `acs validate` rejects out-of-policy handoffs. |
+| **Capability discovery (Agent Cards)** | A2A: agents advertise abilities via JSON Agent Cards so peers know what they can do. [[#3]](#references) | `acs roles` and `acs role explain <ROLE>` expose each role's inputs, outputs, and allowed artifact types — the role profile is the Agent Card. |
+| **Tasks & artifacts as the unit of exchange** | A2A: communication centers on tasks with lifecycles; artifacts are the task outputs. [[#4]](#references) | Every `acs` operation is keyed by `--task <TASK_ID>`; `artifacts/` holds the schema-validated outputs of each role's task phase. |
+| **Durable, resumable workflows** | Microsoft `checkpoint_storage` / `FileCheckpointStorage` lets workflows pause and resume hours or days later. [[#2]](#references) | The Git-tracked store *is* the checkpoint. Any agent on any machine can `git pull` and resume from the last validated handoff. |
+| **Runtime-agnostic interoperability** | A2A: opaque agents on different frameworks collaborate without sharing memory or internal state. [[#4]](#references) | Cursor, Claude Code, Codex, and CI agents collaborate purely through validated artifacts and handoff records — no shared runtime, no shared memory. |
+| **Auditable handoff history** | A2A emphasizes observability and auditability for enterprise use. [[#4]](#references) | `audit/`, `index.json`, `acs handoff list`, and Git history give a complete, reviewable trail of every handoff. |
+
+In short: industry handoff frameworks model handoffs as in-process tool calls between live agent instances. `acs` models them as **persisted, schema-validated, Git-reviewable contracts** — making the same pattern work across role boundaries, agent runtimes, machines, and time.
+
+### References
+
+1. OpenAI Agents SDK — Handoffs: <https://openai.github.io/openai-agents-python/handoffs/>
+2. Microsoft Agent Framework — Handoff Orchestration: <https://learn.microsoft.com/en-us/agent-framework/workflows/orchestrations/handoff?pivots=programming-language-csharp>
+3. Google Developers Blog — A2A: A new era of agent interoperability: <https://developers.googleblog.com/en/a2a-a-new-era-of-agent-interoperability/>
+4. A2A Project — Agent2Agent protocol repository: <https://github.com/a2aproject/A2A>
+
 ## Developing This Repository
 
 If you want to modify or test the toolkit itself, see [DEVELOPMENT.md](DEVELOPMENT.md).

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

@@ -32,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
@@ -40,14 +60,14 @@ 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>

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,9 +1,32 @@
 {
   "name": "agent-context-store",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "description": "acs CLI for Agent Context Store Toolkit.",
   "type": "module",
   "license": "MIT",
+  "keywords": [
+    "ai",
+    "ai-agent",
+    "ai-agents",
+    "agentic-engineering",
+    "multi-agent",
+    "agent-handoff",
+    "a2a",
+    "agent2agent",
+    "context",
+    "context-store",
+    "context-engineering",
+    "sdlc",
+    "claude",
+    "claude-code",
+    "cursor",
+    "codex",
+    "openai-agents",
+    "agent-framework",
+    "schema-validated",
+    "git-backed",
+    "cli"
+  ],
   "homepage": "https://github.com/max9159/agent-context-store#readme",
   "repository": {
     "type": "git",
@@ -23,7 +46,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.4.2",
-    "agent-context-store-core": "0.2.9"
+    "agent-context-store-core": "0.2.11"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json"