troth-dev

Troth is a spec-driven task manager for AI coding agents. Write a feature specification, decompose it into executable tasks with file scopes and verification gates, and let Claude Code run them autonomously.

Install

Run without installing:

npx troth-dev init
# or
bunx troth-dev init

Or install globally:

npm install -g troth-dev
# or
bun add -g troth-dev

Then initialize any project:

troth init

Getting started

troth init                   # set up .troth/ in the current repo
troth login                  # authenticate with Troth cloud
troth bootstrap              # scan the codebase and seed specs

Working with specs and tasks

troth spec list              # list all specs
troth spec show <name>       # view a spec
troth spec new <name>        # create a new spec

troth decompose <spec>       # break a spec into tasks
troth tasks <spec>           # list tasks for a spec
troth task show <spec> <task>
troth task start <spec> <task>
troth task done <spec> <task> --notes "..."

troth next                   # ready tasks
troth next --parallel 3      # conflict-free tasks for parallel dispatch
troth status                 # project-wide status
troth guide                  # full workflow reference

Run troth help or troth <command> --help for the full CLI.

How it works

1. Write specs — describe features in markdown with intent, acceptance criteria, and constraints
2. Decompose — Troth breaks specs into executable tasks with file scopes and verification gates
3. Execute — Claude Code runs tasks autonomously, guided by rich context
4. Verify — automated verification gates confirm each task meets its criteria

For AI agents (Session opener)

When the user mentions work on a Troth project, your FIRST action MUST be to call the start_session MCP tool. It returns:

• Foundations — workspace and project constitutions, design bible, tokens, asset paths
• Briefing — last decision, current drift, what changed recently
• Next tasks — top 5 ready tasks in priority order

Do not call get_foundations, get_briefing, and next_tasks separately at session open — start_session composes all three in one call.

MCP server

Troth ships a hosted Model Context Protocol server at mcp.troth.dev for use from claude.ai web conversations. From Claude Code, use the troth CLI directly — do not call MCP tools.

Health check:

curl https://mcp.troth.dev/health

Full operator notes (deploys, graceful shutdown, SSE tuning) live in docs/.

Requirements

• Node.js 18+ or Bun 1.0+
• Claude Code CLI (for task execution)

Links

• Docs: https://docs.troth.dev
• Site: https://troth.dev

License

MIT