agent-context-store 0.2.10 → 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/package.json

@@ -1,9 +1,32 @@
 {
   "name": "agent-context-store",
-  "version": "0.2.10",
+  "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.10"
+    "agent-context-store-core": "0.2.11"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json"