An agent harness for doc-driven development — with git-native progress tracking.

English | 中文

# Interactive setup guide
npx ystack

# New project with opinionated defaults
npx ystack create my-app

# Add to an existing project
cd your-project && npx ystack init

---

Why

Most AI agent setups have a dirty secret: the context they feed the agent is separate from the docs humans read. You end up maintaining two sources of truth — one rots, the other drifts, and neither is reliable.

ystack makes your documentation site the single source of truth for both humans and agents.

Hard rule: docs reflect only completed work. No "planned", no "coming soon", no six-month-old TODOs. If it's in the docs, it's built, verified, and working. The gap between docs and reality is always zero.

This means agents get accurate context every time — not hallucinated architecture, not aspirational specs, not stale planning artifacts that nobody maintains.

See PHILOSOPHY.md for the full design rationale.

---

How It Works

Three layers, connected by a module registry:

Each module maps a doc page and code scope:

{
  "modules": {
    "payments": {
      "doc": "shared/payments",
      "scope": ["packages/payments/**", "apps/api/src/routes/payments.*"]
    }
  }
}

---

The Workflow

Commands

Command	What it does
/scaffold	Takes a big plan, splits into module doc stubs + diagrams + progress files
/import	Scans existing repo, generates module registry, flags doc gaps
/build <feature>	Reads docs + code, surfaces assumptions, creates a plan. You confirm.
/go	Executes the plan — fresh subagent per task, atomic commits
/qa [--fix]	Runs plan-driven QA and writes QA-REPORT.md; --fix opts into automatic remediation
/quick	Fast path for bug fixes, chores, small changes — skip planning and progress
/review	QA-aware code review — trusts QA-REPORT.md evidence and checks diff-only risks
/docs	Updates documentation for completed work (only completed, never planned)
/pr	Verify, docs check, create PR
/address-review	Fetch PR review comments, triage by priority, address approved fixes

---

Getting Started

# New project
npx ystack create my-app

# Existing project
cd your-project
npx ystack init

See INSTALL.md for full setup options, prerequisites, and configuration.

Documentation

• PHILOSOPHY.md — Design principles and rationale
• INSTALL.md — Installation and default stack
• LINTING.md — Agent linting rules
• RUNTIMES.md — Multi-runtime support

Contributing

Issues and PRs welcome. Please open an issue before starting large changes.

Changelog

See CHANGELOG.md for release history.

License

MIT