agent-context-store

Agent Context Store

Agent Context Store (acs) is a Git-backed handoff toolkit for BA, SA, Dev, and QA agents to produce validated SDLC artifacts — SRS, design docs, ADRs, API specs, test plans — and relay them through confirmed handoff records. Works with Cursor, Claude Code, Codex, CI, and custom runtimes.

Concept Overview

ACS turns tacit knowledge trapped in AI chat sessions into formal deliverables that teams can relay, verify, and retain.

The three diagrams below explain the value, relay flow, and benefits of using ACS. For implementation details, see Architecture.

1 · Problem vs Solution

flowchart LR
    subgraph BEFORE["❌ Without ACS"]
        direction LR
        B1["Requirements scattered in chat history"]
        B2["Design passed verbally — easy to miss items"]
        B3["Switch AI tools and context is lost"]
        B4["No way to confirm the previous role finished"]
    end

    subgraph AFTER["✅ With ACS"]
        direction LR
        A1["Each task has a complete document pack"]
        A2["Handoff checklist — next role must read and confirm"]
        A3["Same context shared across Cursor, Claude, etc."]
        A4["Verifiable, traceable, auditable"]
    end

    BEFORE -->|"Introduce ACS"| AFTER

2 · Relay flow

People describe what they need; AI follows role playbooks to produce standardized documents and handoff records; the next role reads the full task pack before starting.

flowchart TD
    PM(["👤 Product / Business"])
    ARCH(["👤 Architecture / Tech"])
    DEV(["👤 Developer"])
    QA(["👤 QA / Tester"])

    subgraph AI["🤖 AI Assistant (Cursor · Claude · Codex)"]
        direction TB
        AI1["Reads role playbook on start"]
        AI2["Produces standardized documents"]
        AI3["Creates handoff record on completion"]
    end

    subgraph STORE["📁 Shared Project Folder (ACS)"]
        direction TB
        DOC1["📄 Requirements docs"]
        DOC2["📐 Design docs"]
        DOC3["💻 Implementation notes"]
        DOC4["✅ Test plans"]
        HANDOFF["📋 Handoff checklist"]
    end

    PM -->|"Describe the need"| AI
    ARCH -->|"Confirm design direction"| AI
    DEV -->|"Direct implementation"| AI
    QA -->|"Request validation"| AI

    AI --> DOC1 & DOC2 & DOC3 & DOC4
    AI --> HANDOFF
    HANDOFF -->|"Next role reads before starting"| AI
    STORE --> AI

3 · Benefits

mindmap
  root((Benefits of using ACS))
    For individuals
      No repeating background every session
      Switch AI tools without starting from zero
      Clear on what this leg must deliver
    For teams
      Requirements to design to dev to QA relay
      Handoff checklist reduces missed items
      Consistent format — easy to find and compare
    For the organization
      Traceable — who delivered what and when
      Auditable — meets process and quality gates
      Scalable — one store shared across projects

┌─────────────────────────────────────────────────────────────────────┐
│  What you get with ACS                                              │
├─────────────────────────────────────────────────────────────────────┤
│  📦 Complete task pack    End-to-end docs from requirements to QA   │
│  🔗 Reliable handoff      Formal checklist, not "remember to tell"  │
│  🧠 Cross-session memory  Context survives tool or people changes   │
│  ✅ Verifiable start      Next role confirms previous leg is done   │
│  📜 Full history          Git-backed — investigate, restore, audit  │
└─────────────────────────────────────────────────────────────────────┘

Prerequisites

• Node.js >=20
• Git
• A project repository or folder

Step 1: Install the CLI

npm install -g agent-context-store
acs --help

Step 2: Initialize the store

Run acs init in your project directory. When stdin is a terminal, an interactive wizard guides you through three choices:

acs init
? How should the context store be hosted?
  ❯ in-repo   — .acs/ lives inside this project (default)
    local     — stored in your user data dir, nothing committed
    dedicated — a separate repo shared across multiple projects

? Path to the dedicated store repo:   ← only shown for dedicated mode

? Install agent skill files? (space to toggle)
  ✓ Claude Code  → ~/.claude/skills/
  ✓ Cursor       → ~/.cursor/skills/
  ○ Codex        → ~/.codex/skills/

For the full command list, see Commands.

Step 3: Run Your First Workflow

After setup, each team member opens their AI agent (Codex, 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.

AI Agent Skill invocation syntax

• For Codex, Cursor or Claude Code: /acs-ba, /acs-sa, /acs-dev, /acs-qa

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".

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

The agent ends its response with a structured `[HANDOFF: BA → SA | DEMO-0001]` prompt for the SA agent to pick up.

Use Case 2 — SA produces system design

Human → Cursor / Claude Code:

/acs-sa Pick up DEMO-0001 from BA. Design the OTP login system.

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
acs handoff create --from sa --to dev --task DEMO-0001
acs package --task DEMO-0001 --role dev
acs index

The agent ends its response with a `[HANDOFF: SA → DEV | DEMO-0001]` prompt.

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.

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
acs index

The agent ends its response with a `[HANDOFF: DEV → QA | DEMO-0001]` prompt.

Use Case 4 — QA validates and closes the task

Human → Cursor / Claude Code:

/acs-qa Write the test plan for DEMO-0001.

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
acs index

All four role artifacts and handoff records are now persisted in the store.

Context Store Layout

• In in-repo mode the store root is .acs/; in dedicated mode it is the store repository root.
• Role deliverables are written under artifacts/{task_id}/{type}/ (for example artifacts/DEMO-0001/srs/SRS-DEMO-0001.md);
• Handoff records go to handoffs/;
• Context bundles for the next role go to packages/.

For the full directory tree and file-by-file guide, see ACS Context Store Full Content Guide.

Commands

acs package includes a context budget advisory in Markdown and JSON output. Use --max-tokens <N> to override the configured budget for one run. The CLI does not split or rewrite artifacts; role skills decide semantic phase documents when the advisory reports warning, high, or split_recommended. | acs doctor | Runs the same validation checks as acs validate for quick health checks. |

Full syntax

acs --version
acs init [path] [--mode <in-repo|local|dedicated>]
acs link <existing_store_path> [--path <project_path>] [--force]
acs status
acs install-skills --agent <cursor|claude|codex|openclaw|all> [--path <path>]
acs roles
acs role explain <ROLE> [--task <TASK_ID>]
acs new <ARTIFACT_TYPE> [--role <ROLE>] --task <TASK_ID> [--title <TITLE>]
acs <ROLE> new <ARTIFACT_TYPE> --task <TASK_ID> [--title <TITLE>]
acs next --role <ROLE> --task <TASK_ID>
acs validate [--role <ROLE>] [--task <TASK_ID>] [--artifact <PATH>]
acs handoff create --from <ROLE> --to <ROLE> --task <TASK_ID>
acs handoff check <HANDOFF_ID_OR_PATH>
acs handoff check --from <ROLE> --to <ROLE> --task <TASK_ID>
acs handoff list [--task <TASK_ID>] [--role <ROLE>]
acs package --task <TASK_ID> --role <ROLE> [--format markdown|json] [--max-tokens <N>]
acs <ROLE> package --task <TASK_ID> [--format markdown|json] [--max-tokens <N>]
acs index
acs doctor

Aligned with Industry Handoff Standards

acs applies handoff patterns from the OpenAI Agents SDK, Microsoft Agent Framework, and Google's Agent2Agent (A2A) protocol to BA, SA, Dev, and QA — persisting each handoff to Git as a schema-validated, reviewable contract rather than an in-memory tool call, so work survives across runtimes, sessions, and CI.

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

Contributing

To build, test, or contribute to ACS, see the Development Guide.