Add: A State Machine-Based Agent-Driven Development Workflow System

Add is a set of personal pluggable agent skills designed specifically for managing the software development lifecycle. Its core innovation lies in using a state machine model to organize workflows—each state transition corresponds to a new session, solving the context drift problem in long-term agent conversations. Work states are stored in the MASTER.md tracker and structured story files instead of conversation history, supporting both Claude Code and Codex platforms.

The core problem Add system addresses is context drift in long agent conversations: when the context window is full, the model tends to generate hallucinated file paths, lose early instructions, and a single wrong decision cascades and amplifies due to the lack of a clean state reset.

Add defines a clear state lifecycle; each story goes through a complete process from planning to completion: create an epic via /epic-plan to generate MASTER.md, plan pending stories with /epic-story-plan, claim and implement using TDD via /epic-story-claim, resume interrupted work with /epic-story-resume, and finally review the implementation with /epic-story-review. The design principles are: each command does one thing, each session executes one command, and review and coding sessions are separated to avoid bias.

Add elevates TDD to a planning-phase constraint: /epic-story-plan requires providing a validation proof matrix, mapping acceptance criteria to test seams to ensure a clear testing strategy before coding. The session handover mechanism records changes, remaining work, and next steps by writing a 'Session Handover' section; knowledge retention is achieved via /memorize to reflect on friction points and suggest document patches, and /epic-squash merges completed specifications into CONTRACT.md to prevent repeated learning.

Add supports both Claude Code and Codex platforms, offering two installation paths: installation via the Claude Code plugin market, or installation via a custom shell script (supports user-level/project-level scopes, implemented via symbolic links; updates only require git pull, and script script idempotency prevents overwriting non-symbolic links).

Add includes 10 core workflow commands (such as /epic-plan for creating epics, /epic-story-claim for claiming stories, /epic-story-review for reviewing implementations, etc.) and 2 tool commands: /grillme for continuous questioning in planning/design to reach consensus, and /memorize for reflecting on session friction and suggesting document improvements. All commands share the state lifecycle and coordinated file conventions.

Add is suitable for complex long-term projects or multi-developer collaboration scenarios, solving agent conversation limitations through externalized states. For individual developers: the structured work approach maintains focus and reduces context switching costs; for teams: it standardizes collaboration language and processes, lowering communication overhead. It also demonstrates a new collaboration paradigm: breaking down into multiple short, focused sessions to leverage AI capabilities while avoiding their limitations.

The core insight of the Add project is: the real state should be stored in the file system而非对话历史. The state machine workflow built on this not only solves the context drift problem but also provides a new way of thinking for collaborating with AI. For other developers, Add provides a reference implementation, and its session handover and knowledge retention processes can be adapted to other workflows and toolchains.