From 2bcb5702444aab7eca9b5b374f8de338bfd38a53 Mon Sep 17 00:00:00 2001 From: architect-bot Date: Wed, 15 Apr 2026 18:14:08 +0000 Subject: [PATCH] sprint: update example-project-lifecycle.md --- sprints/example-project-lifecycle.md | 139 ++++++++++++++++++--------- 1 file changed, 93 insertions(+), 46 deletions(-) diff --git a/sprints/example-project-lifecycle.md b/sprints/example-project-lifecycle.md index 11ab658..ccd99e2 100644 --- a/sprints/example-project-lifecycle.md +++ b/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 - -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) +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 ` fully bootstraps a project: creates repos, ops repo, branch protection, - issue templates, VISION.md template, docker-compose stack, cron scheduling -- Dev-agent pipeline is proven: issue → branch → implement → PR → CI → review → merge -- Review-agent, gardener, supervisor all operational -- Project TOML templates exist (`projects/*.toml.example`) -- Issue template for bug reports exists; `disinto init` copies it to target repos - -What's missing: an actual example project repo with seed content and seed issues that -demonstrate the loop. +- `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 - -Files touched: 3-5 in the disinto repo (documentation, possibly `disinto init` tweaks) -New artifacts: 1 example project repo with seed files, 3-5 seed issues -Subsystems: bootstrap, dev-agent, CI, review -Sub-issues: 3-4 -Gluecode ratio: ~70% content/documentation, ~30% scripting +- ~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 - -- **Maintenance burden**: The example project must stay working as disinto evolves. - If `disinto init` changes, the example may break. Mitigation: keep the example - minimal so there's less surface to break. -- **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. +- **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 example project repo (hosted on Forgejo, mirrored to Codeberg/GitHub) -- Seed issues re-created on each fresh `disinto init` run (or documented as manual step) -- No new services, agents, or cron jobs +- 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. -Worth it. This is the single most impactful adoption artifact. A working example -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 -machine without language-specific dependencies. +## 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) + -- 2.49.1