Metadata-Version: 2.4
Name: living-projects
Version: 0.1.2
Summary: How to build software with agents that don't remember anything.
Project-URL: Homepage, https://github.com/beverage/living-projects
Project-URL: Repository, https://github.com/beverage/living-projects
Author-email: Alex Beverage <alex@beverage.me>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Requires-Python: >=3.11
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# Living Projects

How to build software with agents that don't remember anything.

Living Projects is a small set of files and skills that lets a project remember itself across sessions, so the agent picks up where you left off and you stop carrying the project in your head.

I built this after a year of building [Levelang](https://levelang.app) across more than a hundred Claude Code sessions, where every session began with the same warmup of retyping context and re-explaining decisions. The full argument is in [MANIFESTO.md](https://github.com/beverage/living-projects/blob/main/MANIFESTO.md).

## Quickstart

Install into a new or existing project directory:

```
uvx living-projects init
```

The installer asks for the project name and your name, refuses to overwrite existing state on disk, and writes the substrate skeleton to `.product/`, `.claude/`, and `.living-project/`. `uvx` resolves and runs the latest release from PyPI in an ephemeral environment — no clone, no global Python footprint, no install to remember.

For non-interactive runs:

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

After init, three moves get the project remembering:

1. Open `.product/context/` and fill in the stub files. Start with `principal.md`, `product.md`, and `principles.md` — they shape every recommendation the substrate makes after that. Most files are short.
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 ships with init

Eleven skills land as slash commands in 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.

Plus two rules the agent reads:

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

## What's not here yet

v0.1 ships the install path and the skills. The following are explicit follow-ups, not omissions:

- **Retrieval substrate** — opt-in `enable-retrieval` for embedding-based recall over `.product/`. Deferred to v0.2 ([DEC-006](https://github.com/beverage/living-projects/blob/main/.product/decisions/DEC-006-retrieval-substrate-optional.md)).
- **`update` subcommand** — propagate substrate changes into existing installs without overwriting your customizations.
- **Brand-asset pack** — separate skill pack for projects that need style asset management.
- **Onboarding skills** — guided first-session experiences that walk you through the stub context files.
- **`doctor` health checks beyond presence** — v0.1 only verifies the four substrate paths exist.

## Where to look around

- [MANIFESTO.md](https://github.com/beverage/living-projects/blob/main/MANIFESTO.md) — the longer argument: why this exists and what it's trying to do.
- [.product/](https://github.com/beverage/living-projects/tree/main/.product) — the substrate dogfooding itself. Worked example of what a filled-in `.product/` looks like.
- [.claude/](https://github.com/beverage/living-projects/tree/main/.claude) — the skills and rules that ship with init, in source form.
- [Backlog](https://github.com/beverage/living-projects/tree/main/.product/backlog) — what's open, what's deferred, what's been archived.
- [Decisions](https://github.com/beverage/living-projects/tree/main/.product/decisions) — the architectural calls and why they were made.

If something breaks or feels wrong, the [issue tracker](https://github.com/beverage/living-projects/issues) 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](https://github.com/beverage/living-projects/blob/main/LICENSE) and [NOTICE](https://github.com/beverage/living-projects/blob/main/NOTICE).
