disinto-ops/sprints/example-project-lifecycle.md

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.

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.
• Issue templates exist in templates/issue/ (bug report format) and are auto-copied during init.
• .woodpecker/ci.yml provides a working CI pipeline template (ShellCheck + phase-test).
• Docker Compose stack generation handles Forgejo + Woodpecker + agents containers.
• Project TOML config (projects/*.toml) is well-defined with scheduling, monitoring, and optional llama agent support.
• Dev-agent, review-agent, and gardener are battle-tested on the disinto repo itself.
• The lib/generators.sh helper generates Compose files and cron entries.
• Ops repo structure (vault, journal, knowledge, evidence, sprints) is seeded by init.

Complexity

• ~8-12 files across 3-4 subsystems (example repo content, seed issues, CI config, documentation).
• Estimated 5 sub-issues.
• ~80% gluecode (wiring existing init + agents to a new repo), ~20% greenfield (example app code, seed issues, README walkthrough).

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.
• 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.
• 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.
• 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.

Cost — new infra to maintain

• One new Forgejo repository (the example project) — trivial storage, no compute.
• One new ops repo (auto-created by init) — same.
• Seed issues need occasional refresh if factory conventions evolve (low frequency).
• 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.

Sub-issues

• 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)