sprints/example-project-lifecycle.md

@@ -1,62 +1,109 @@
-# Sprint: example project — full lifecycle demo
+# Sprint: example-lifecycle
 
 ## Vision issues
 - #697 — vision: example project demonstrating the full disinto lifecycle
 
 ## What this enables
-
+New users can see disinto work end-to-end in under 10 minutes. Today, the only way to understand the factory is to read VISION.md and AGENTS.md — there is no runnable proof. After this sprint, a self-contained example project exists that demonstrates: `disinto init` → seed issues land in backlog → dev-agent picks one up → CI runs → review-agent approves → merge. This is the primary onboarding asset for the Adoption milestone and the showcase for the landing page.
-After this sprint, a new user can see disinto working end-to-end on a real project:
-`disinto init` → seed issues appear → dev-agent picks one up → PR opens → CI runs →
-review-agent approves → merge → repeat. The example repo serves as both proof-of-concept
-and onboarding reference.
-
-This unblocks:
-- **Adoption — Example project demonstrating full lifecycle** (directly)
-- **Adoption — Landing page** (indirectly — the example is the showcase artifact)
-- **Contributors** (lower barrier — people can see how disinto works before trying it)
 
 ## What exists today
-
+- `disinto init` is functional and idempotent — creates Forgejo repo, ops repo, bot users, branch protection, Woodpecker CI, project TOML, and activates dev/review/gardener agents. Blockers #425 and #688 are both closed.
-- `disinto init <url>` fully bootstraps a project: creates repos, ops repo, branch protection,
+- Issue templates exist in `templates/issue/` (bug report format) and are auto-copied during init.
-  issue templates, VISION.md template, docker-compose stack, cron scheduling
+- `.woodpecker/ci.yml` provides a working CI pipeline template (ShellCheck + phase-test).
-- Dev-agent pipeline is proven: issue → branch → implement → PR → CI → review → merge
+- Docker Compose stack generation handles Forgejo + Woodpecker + agents containers.
-- Review-agent, gardener, supervisor all operational
+- Project TOML config (`projects/*.toml`) is well-defined with scheduling, monitoring, and optional llama agent support.
-- Project TOML templates exist (`projects/*.toml.example`)
+- Dev-agent, review-agent, and gardener are battle-tested on the disinto repo itself.
-- Issue template for bug reports exists; `disinto init` copies it to target repos
+- The `lib/generators.sh` helper generates Compose files and cron entries.
-
+- Ops repo structure (vault, journal, knowledge, evidence, sprints) is seeded by init.
-What's missing: an actual example project repo with seed content and seed issues that
-demonstrate the loop.
 
 ## Complexity
-
+- ~8-12 files across 3-4 subsystems (example repo content, seed issues, CI config, documentation).
-Files touched: 3-5 in the disinto repo (documentation, possibly `disinto init` tweaks)
+- Estimated 5 sub-issues.
-New artifacts: 1 example project repo with seed files, 3-5 seed issues
+- ~80% gluecode (wiring existing init + agents to a new repo), ~20% greenfield (example app code, seed issues, README walkthrough).
-Subsystems: bootstrap, dev-agent, CI, review
-Sub-issues: 3-4
-Gluecode ratio: ~70% content/documentation, ~30% scripting
 
 ## Risks
-
+- **Flaky demo path**: if any agent misbehaves on the example repo, it undermines trust instead of building it. The example must work reliably on a clean `disinto init`.
-- **Maintenance burden**: The example project must stay working as disinto evolves.
+- **Scope creep**: temptation to make the example app "interesting" (web app, API, etc.) when the point is demonstrating the factory, not the app. A trivial app that completes the loop is better than an ambitious app that doesn't.
-  If `disinto init` changes, the example may break. Mitigation: keep the example
+- **Maintenance drift**: the example repo becomes stale if disinto conventions change and nobody updates it. Seed issues and CI config must track the factory's current expectations.
-  minimal so there's less surface to break.
+- **Bootstrap dependency**: if `disinto init` has undiscovered edge cases on fresh installs (vs. the existing deployment), the example will surface them — which is useful but could block the demo.
-- **CI environment**: The example needs a working Woodpecker pipeline. If the
-  example uses a language that needs a specific Docker image in CI, that's a dependency.
-  Mitigation: choose a language/stack with zero build dependencies.
-- **Seed issue quality**: If seed issues are too vague, the dev-agent will refuse them
-  (`underspecified`). If too trivial, the demo doesn't impress. Need a sweet spot.
-- **Scope creep**: "Full lifecycle" could mean bootstrap-to-deploy. For this sprint,
-  scope to bootstrap-to-merge. Deploy profiles are a separate milestone.
 
 ## Cost — new infra to maintain
-
+- One new Forgejo repository (the example project) — trivial storage, no compute.
-- One example project repo (hosted on Forgejo, mirrored to Codeberg/GitHub)
+- One new ops repo (auto-created by init) — same.
-- Seed issues re-created on each fresh `disinto init` run (or documented as manual step)
+- Seed issues need occasional refresh if factory conventions evolve (low frequency).
-- No new services, agents, or cron jobs
+- No new services, no new scheduled tasks, no new formulas, no new agent roles.
 
 ## Recommendation
+**Worth it.** This is the single highest-leverage item on the Adoption milestone. The factory's credibility depends on a working demo, and all prerequisites are now unblocked (#425, #688 closed). Scope should be kept deliberately minimal — a "hello world" level app with 3-5 seed issues that exercise the core loop. Resist the urge to showcase every feature; the goal is one clean pass through issue → PR → CI → review → merge. Ship this before the landing page references it.
 
-Worth it. This is the single most impactful adoption artifact. A working example
+## Sub-issues
-answers "does this actually work?" in a way that documentation cannot. The example
+
-should be dead simple — a static site or a shell-only project — so it works on any
+<!-- filer:begin -->
-machine without language-specific dependencies.
+- id: example-repo-scaffold
+  title: "vision(#697): scaffold example project repository with minimal app and CI config"
+  labels: [backlog]
+  depends_on: []
+  body: |
+    ## Goal
+    Create the example project repository content: a minimal application (e.g., a single-file CLI tool or static site), a `.woodpecker/ci.yml` pipeline, a `VISION.md`, issue templates, and a `README.md` explaining what this repo demonstrates.
+    ## Acceptance criteria
+    - [ ] Repository contains a working application with at least one testable behavior
+    - [ ] `.woodpecker/ci.yml` runs lint + tests and passes on the initial commit
+    - [ ] `VISION.md` describes the example project's purpose in factory terms
+    - [ ] Issue templates copied from `disinto/templates/issue/`
+    - [ ] `CLAUDE.md` with project-specific agent instructions
+
+- id: example-bootstrap-script
+  title: "vision(#697): create bootstrap script that runs disinto init for the example project"
+  labels: [backlog]
+  depends_on: [example-repo-scaffold]
+  body: |
+    ## Goal
+    Provide a single command or script that bootstraps the example project on a fresh disinto installation, creating the repo on Forgejo, running `disinto init`, and confirming the stack is healthy.
+    ## Acceptance criteria
+    - [ ] Script calls `disinto init` with correct arguments for the example repo
+    - [ ] Script verifies Forgejo repo, ops repo, and Woodpecker CI are configured
+    - [ ] Script is idempotent (safe to re-run)
+    - [ ] Documented in the example project README
+
+- id: example-seed-issues
+  title: "vision(#697): file seed issues that exercise the full dev-agent loop"
+  labels: [backlog]
+  depends_on: [example-bootstrap-script]
+  body: |
+    ## Goal
+    Create 3-5 seed issues on the example project's Forgejo repo, labeled `backlog`, that the dev-agent can pick up and implement. Issues should be small, well-specified, and progressively demonstrate the factory lifecycle.
+    ## Acceptance criteria
+    - [ ] At least 3 seed issues filed with `backlog` label
+    - [ ] Each issue has clear acceptance criteria the dev-agent can verify
+    - [ ] At least one issue triggers a CI-visible change (e.g., adds a test)
+    - [ ] Issues are ordered by dependency so dev-agent picks them up sequentially
+    - [ ] Dev-agent successfully implements at least one seed issue end-to-end
+
+- id: example-lifecycle-verification
+  title: "vision(#697): verify full lifecycle loop — issue through merge — on example project"
+  labels: [backlog]
+  depends_on: [example-seed-issues]
+  body: |
+    ## Goal
+    Run the factory agents on the example project and verify the complete loop: dev-agent picks up a seed issue → creates PR → CI passes → review-agent approves → PR merges → issue closes.
+    ## Acceptance criteria
+    - [ ] Dev-agent claims a seed issue and opens a PR
+    - [ ] Woodpecker CI runs and passes on the PR
+    - [ ] Review-agent posts a review and approves
+    - [ ] PR is merged and issue is closed
+    - [ ] No manual intervention required for the happy path
+
+- id: example-onboarding-readme
+  title: "vision(#697): write onboarding README documenting the example for new users"
+  labels: [backlog]
+  depends_on: [example-lifecycle-verification]
+  body: |
+    ## Goal
+    Write comprehensive documentation in the example project's README that walks a new user through what happened, what each agent did, and how to replicate it for their own project.
+    ## Acceptance criteria
+    - [ ] README explains the factory model in concrete terms using the example
+    - [ ] README links to relevant disinto docs (VISION.md, AGENTS.md)
+    - [ ] README includes a "try it yourself" section with `disinto init` instructions
+    - [ ] README shows the timeline of a completed lifecycle loop (issue → merge)
+<!-- filer:end -->