Katastasi

The open-source documentation, task-tracking & testing framework that keeps your project honest.

Katastasi (Greek κατάστασις, "status / state") answers the question every team fumbles: what is the real status — is this actually done, and verified, right now?

Local-first markdown is the source of truth (works fully offline, no SaaS, no Jira required). It's agent-native (an MCP server so Claude/Copilot can drive it) and integrates everywhere — Jira, Confluence, GitHub/GitLab issues, CI/CD, custom scripts — but those are optional projections you sync to, never prerequisites.

requirements  ⇄  tasks  ⇄  tests  ⇄  results        (one traceable model, in markdown)
      │             │          │
   Confluence     Jira     your test suites           (optional, synced projections)

MIT-licensed and free to self-host. New here? See VISION.md for the full picture and roadmap.

Coding agent or contributor? Start with AGENTS.md. Adopting it on a team? See the methodology — the per-feature loop (onboard → design → implement → verify → sync) and where it slots into PRs/CI.

Three pillars

| Pillar | What you get | |---|---| | 📄 Documentation | Markdown ⇄ Confluence/Jira, both ways, round-trippable, mermaid preserved. Interactive decision docs (katastasi questions). Optional AI-authored technical analysis. | | ✅ Task tracking | A local, markdown task model (.acp/tasks) linked to requirements and tests, usable standalone or imported read-only from Jira. A task marked done whose requirements aren't verified is flagged ⚠️ — "is done really done?" at the task level. | | 🧪 Testing | Links and runs your existing suites (Playwright/Jest/Vitest/node/xUnit), plus a built-in requirement-first acceptance runner (katastasi test — HTTP + CLI) — all joined to requirements at the git commit → a true, per-requirement status with regression detection. |

Get started

New to it? docs/GET_STARTED.md has a copy-paste prompt for your AI agent (Claude Code / Copilot / Cursor) and the equivalent commands.

Install

# Run without installing (recommended)
npx katastasi trace init
npx katastasi --help

# Or install globally
npm i -g katastasi            # also published as @dloizides/katastasi

# Or Docker
docker run --rm -v "$PWD:/work" -w /work ghcr.io/openmindednewby/katastasi trace

Binary is katastasi (short alias kat; acp still works through the transition).

Quick start — requirements traceability

Answer "which requirements actually hold true, at this commit?" by linking your tests to requirements (a Jira epic, a markdown spec, roadmap.html, a Confluence page, or GitHub/GitLab issues) and joining them with the test results.

katastasi trace init                        # autodetect frameworks + requirements → acp-trace.json
katastasi trace serve                       # web portal: live dashboard + ▶ Run buttons + history
katastasi trace --run --fail-on regression  # CI: re-run suites, trace, fail on any regression

Each requirement is classified ✅ verified / ❌ failing / 🧪 unverified / 📋 specified, flagged ⚠️ drift when it's declared done but isn't verified, and a requirement going verified → failing is a ⛔ regression. Tag tests inline (test('login works @PROJ-123', …), [Trait("req","PROJ-123")]) or list them in a mapping file. Full guide: docs/TRACEABILITY.md · 5-minute setup: docs/ONBOARDING.md.

Business requirements → development-ready

Gather requirements from a mix of sources, find the gaps against the codebase, capture open decisions as an interactive form, then turn it all into a technical analysis + tasks + tagged test stubs:

katastasi trace pull-requirements   # mixed sources (Jira/Confluence/md/issues/script) → local folder
katastasi trace gaps                # which requirements aren't in code / lack tests / aren't verified
katastasi pipeline                  # one command: gather → gaps → analyze → tech doc + tasks + tests
katastasi pipeline --ask            # two-pass: open-questions form first, then --answers

katastasi analyze (AI) produces a gap analysis, a Confluence-ready technical-analysis page, Jira tasks (acceptance criteria + use-case flow), and scaffolded tagged unit/e2e test stubs — local and/or published. Guide: docs/TECH_ANALYSIS_FLOW.md.

Feature wizard (idea → dev-ready pack)

One guided flow that turns a feature + its requirements (Jira / Confluence / markdown) + the existing code into a dev-ready package an agent or junior dev can execute without thinking hard — and a self-contained HTML feature pack the developer just reads, approves, and verifies.

katastasi wizard                       # interactive: source → requirements → analyze → tasks → pack
katastasi wizard --feature "Login" --source jira --requirements pull   # scriptable
katastasi wizard check --source both   # are my Jira/Confluence credentials set? (how to fix if not)

It gathers/creates requirements, runs analyze (a system + per-use-case mermaid data-flow + gap analysis), creates ordered, context-rich tasks (code + Jira + Confluence inline, so a low-capability model can execute), and emits unit / e2e / acceptance stubs + ready-made curls — then writes .acp/features/<name>/feature-pack.html (+ a markdown mirror, + optional Confluence page). The developer opens it, reads the data-flow, ticks approve, runs the curls (copy button), ticks verify. First-time Jira/Confluence auth: docs/SOURCES_SETUP.md. Design + roadmap: docs/WIZARD-DESIGN.md.

Task tracking

Local, markdown-first tasks that link to requirements and tests — and stay honest:

katastasi task add "Implement login" --req PROJ-1   # → .acp/tasks/TASK-1.md
katastasi task set TASK-1 done
katastasi task board                                # → .acp/BOARD.md (kanban by status)
katastasi task verify --fail-on drift               # ⚠️ a done task whose reqs aren't verified fails CI

Statuses are configurable (tasks.statuses); IDs are global TASK-<n> or per-scope (WEB-<n>). Set tasks.mode: jira to import issues read-only (katastasi task import). katastasi analyze also drops its generated stories straight onto the board. Agents drive it all via the task_* MCP tools. Full design: docs/PHASE-1-DESIGN.md.

Acceptance testing (requirements that verify themselves)

Attach an executable acceptance test to a requirement and katastasi test runs it — HTTP/REST calls (or CLI commands) with assertions — then writes JUnit results keyed by requirement, so trace flips the requirement to ✅ verified on pass (and clears any task drift). Existing Jest/Playwright suites keep being linked, not replaced.

katastasi test                       # run .acp/tests specs + inline ```acp-test blocks → JUnit
katastasi test --req PROJ-1          # just one requirement
katastasi trace                      # fold the results into per-requirement status

Author them three ways — a spec file (.acp/tests/PROJ-1.acp.json / .acp.yml / a markdown table), or inline under a requirement, terse or JSON:

## PROJ-1 — Login
```acp-test
POST /login {"user":"x","pass":"bad"} -> 401
```

Steps assert status / JSON-path / header / body-contains, capture variables to chain (login → token → reuse), and read secrets from env via {{env.NAME}}. baseUrl, default headers, and a one-time login setup live in the config runner block. katastasi analyze generates these specs straight from the requirements. Agents drive it via the test_run MCP tool. Full guide: docs/ACCEPTANCE.md.

Integrations

• AI agents (MCP): this repo is an MCP server (katastasi-mcp). Agents call requirements_trace, analyze, pull_requirements, scaffold_test, requirement_status, markdown_to_jira, markdown_to_confluence, and more. See docs/CLI_AND_MCP.md and docs/AGENT_PROMPT.md.
• Jira & Confluence (both ways): pull-jira / pull-confluence → markdown folders; edit; push-folder back. Recursive + round-trippable.
• GitHub / GitLab issues: as requirement sources (by label/milestone).
• CI/CD: a published GitHub Action (uses: openmindednewby/[email protected]) plus GitLab CI and pre-commit templates in docs/ci/. Exit non-zero on regression.
• Custom scripts / services: a command requirement source (run any script → requirements), an output.post sink (POST the full report to your server), and a self-hosted collector.
• Local-only markdown: requirements, runs, and reports are plain files you can commit. No external service needed for the core.

AI authoring (optional add-on)

The original flow — describe a feature → AI writes a structured technical analysis → publish to Confluence + create Jira tickets — is retained as an optional module. It runs via the claude / gh models CLIs (no Docker/keys) or via self-hosted n8n (browser UI), with a 13-template registry and team context profiles.

./scripts/cli-preview.sh "Add user notification preferences"        # Claude Code CLI
./scripts/gh-models-preview.sh "Add user notification preferences"  # GitHub Models (free)

Full reference: docs/WORKFLOWS.md · docs/CLI_SETUP.md · docs/SETUP.md · templates in templates/, profiles in team-profiles/.

Roadmap

Katastasi is built MVP-first — a releasable phase every 1–2 weeks. Full detail in VISION.md.

• Phase 0 ✅ — Rebrand & distribution: rename, npm + Docker + GitHub Action (0.2.0).
• Phase 1 ✅ — unified .acp/ model + switchable local/Jira/hybrid task tracking (shipped 0.3.0).
• Phase 2 ✅ — requirement-first acceptance test runner (HTTP + CLI; shipped 0.4.0). See docs/ACCEPTANCE.md.
• Phase 3 ✅ (v1) — bidirectional sync .acp/tasks ⇄ GitHub issues / Jira (3-way reconciler, revision-tracked, conflict-flagging, status round-trip). See docs/SYNC.md. (v2 field-merge, v3 interactive next.)
• Phase 4 — breadth (pytest/go/cypress, more CI) & polish.

Free & paid

Everything in this repo is MIT and free to self-host — the entire CLI, MCP server, runner, sync, and local engine. Paid offerings are only: a hosted cloud (managed dashboard/collector), support, and custom development.

Contributing

Contributions welcome — see CONTRIBUTING.md. Good first steps: a new requirement source, a test-framework adapter, or a CI template.

License

MIT — see LICENSE.