living-projects 0.1.1

An operating model for AI-augmented projects.

Living Projects

An operating model for AI-augmented projects. The substrate gives a project a place to keep its context, decisions, planning, and journal so that AI agents working in the codebase can pick up where the last session left off, and so the human can see what was done and why.

The longer argument is in MANIFESTO.md. The design document that grounds it is at .product/research/product/2026-04-30-living-knowledge-base.md.

Quickstart

Install the substrate into a new or existing project directory:

uvx living-projects init

uvx resolves and runs the latest living-projects release from PyPI in an ephemeral environment. There is no clone, no install, and no global Python footprint. init prompts for a project name and a principal name, refuses to overwrite existing substrate state, and writes the skeleton to .product/, .claude/, and .living-project/.

For non-interactive runs:

uvx living-projects init --project-name myproject --principal "My Name"

After init, three things get the project moving:

1. Open .product/context/ and replace the stubs with real content. The highest-leverage three to start with are principal.md, product.md, and principles.md. They shape every recommendation the substrate makes after that, and without them the planning skill has nothing to ground its suggestions in.
2. Open the directory in Claude Code and run /plan for a tactical recommendation on what to work on first.
3. Run /status any time for a quick orientation.

What's in the box

The substrate ships eleven skills, accessed as slash commands inside Claude Code:

• /plan — tactical recommendation on what to work on next.
• /status — lightweight dashboard of git state, backlog, decisions, and freshness.
• /backlog — add, update, list, close, and archive backlog items.
• /decide — capture an architectural or product decision.
• /research — web research that produces a sourced brief.
• /draft — draft prose in the project's voice.
• /refine — refine existing prose against the project's voice rules.
• /audit — deep self-assessment of project state, producing a persistent artifact.
• /review — review the history and current state of a specific scope.
• /retro — activity summary across a time window.
• /close — session close-out: archive completed items, journal work, verify git state.

Two rules ship alongside them:

• bash-commands.md — shell conventions the agent follows (no cd, no ; outside whitelisted control flow keywords, one construct per call).
• session-init.md — what the agent reads first when a session begins.

What's not in v0.1

The substrate is presence, not feature-complete. v0.1 ships the install path and the skill library. The following are explicit follow-ups:

• Retrieval substrate — opt-in enable-retrieval subcommand to add embedding-based recall over .product/. Deferred to v0.2 (DEC-006).
• update subcommand — propagate substrate changes into existing installs without overwriting principal-customized files.
• Brand-asset pack — a separate skill pack for projects that need brand/style asset management.
• Onboarding skills — guided first-session experiences that fill in the stub context files.
• doctor health checks beyond presence — v0.1 only verifies the four substrate paths exist.

Where to go next

• MANIFESTO.md — the argument: why this exists and what it's trying to do.
• .product/ — the substrate's own dogfooded state. Worked example of what a filled-in .product/ looks like.
• .claude/ — the skills and rules that ship with init, in their source form.
• Backlog — what's open, what's deferred, what's been archived.
• Decisions — the architectural calls and why they were made.

If something breaks or feels wrong, the issue tracker is the right place. The substrate is new in public, and the install path has not yet seen wide use.

License

Apache 2.0. See LICENSE and NOTICE.