janpeter/Scrum4Me
0
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Scrum4Me/docs/adr/0009-three-phase-feature-pipeline.md

6.5 KiB
Raw Blame History

title status date
ADR-0009: Three-phase agent pipeline for feature ideation → plan → implementation proposed 2026-05-03

ADR-0009: Three-phase agent pipeline for feature ideation → plan → implementation

Status

Proposed

Context

Today a new feature-idea has no integrated path inside Scrum4Me. The user either types a PBI/plan by hand, or starts an ad-hoc Claude session outside the app and pastes the result back in. Both routes lose product-context (the agent doesn't see the existing PBIs, sprint, or done stories), lose docs-context (patterns and ADRs are not consulted), and produce plans of varying depth.

Several building blocks exist or are in flight that, on their own, address parts of the problem:

  • M11 — agent ↔ user question channel via persistent table + LISTEN/NOTIFY (docs/plans/M11-claude-questions.md).
  • ST-1111 — "Voer uit"-knop that enqueues a Claude Code job (docs/plans/ST-1111-claude-job-trigger.md).
  • MCP tools — 20 tools that expose product/PBI/story/task/sprint state from the DB.
  • Docs as filesystem — CLAUDE.md, docs/INDEX.md, patterns, ADRs and architecture notes are readable by any agent that has repo access.
  • grill-me skill — relentless interview to surface assumptions and decision-tree branches.
  • Plans-as-files convention — canonical plans live in docs/plans/*.md with front-matter; drafts as _draft-*.md sidecars (docs/obsidian-authoring.md, ADR-0008).

What is missing is the orchestration: a single, repeatable flow that composes these pieces from one entry point on the product page, with explicit human checkpoints, so the user can go from "I have an idea" to "an agent is implementing it" without ad-hoc setup each time.

Decision

We adopt a three-phase agent pipeline, triggered by a "New idea"-button on the product page. Each phase is an independent Job row picked up by the existing Claude Code worker (ST-1111). A human reviews the artefact between each phase; nothing auto-advances.

Fase Job type Input Skill Output
1. Brainstorm FEATURE_BRAINSTORM { productId, ideaText, userId } grill-me docs/plans/_draft-feature-<slug>.md
2. Detail plan DETAIL_PLAN path to draft none (custom system-prompt) docs/plans/ST-XXXX-<slug>.md + PBI/Story/Task rows via MCP
3. Implementation reuses ST-1111 story id (per-story choice) code changes

Each agent gets context from two sources, both via MCP:

  1. DB-context via MCP — get_product, list of PBIs/stories/sprints, related done work (existing 20 tools).
  2. Docs-context via new MCP tools — extend scrum4me-mcp with list_docs, read_doc, search_docs. The agent no longer reads docs/ directly from the filesystem; all docs access is mediated by the MCP server.

This is a deliberate change from the position recorded in docs/obsidian-authoring.md ("the mcp server does not expose docs/ content"). That stance held while docs were only consumed by interactive Claude Code sessions running in the repo. The pipeline introduces background workers and a future where the worker may run outside the repo (container, separate host); MCP-mediated docs access keeps the contract uniform across both modes and lets us version, log, and rate-limit docs reads alongside DB reads.

Plans remain file-based (per current convention). Execution state (jobs, PBIs, stories, tasks, questions) remains DB-based. A lightweight BrainstormSession row may be added in fase 1 to expose status in the UI; the file is the source of truth for content.

Consequences

Positive

  • One predictable flow per feature, replacing ad-hoc Claude sessions outside the app.
  • Each fase is replaceable in isolation (e.g., swap grill-me for a different skill in fase 1 without touching fase 2 or 3).
  • Human review-points between fases prevent runaway agents and let plans land in Obsidian for graph/backlinks inspection before any code is written.
  • Reuses M11, ST-1111, MCP tools and docs-as-filesystem — no new source of truth.
  • Plans created this way are indistinguishable from hand-written plans (docs/plans/ST-XXXX-…md with the same front-matter), so the existing INDEX generator and Obsidian properties UI keep working.

Negative

  • Three job types to define, queue, and observe — more surface area than a single end-to-end agent.
  • Hybrid file/DB model: the pipeline coordinates a file (the plan) with rows (the jobs and DB entities). Mismatches (file deleted, job orphaned) need explicit handling.
  • The grill-me phase can run open-ended if the agent fails to converge. Mitigation: per-session question cap and a "stop and write what you have" timeout.
  • Hard dependency on M11 and ST-1111 being shipped first; cannot start fase-1 implementation until the question channel and job queue are live.
  • Extending scrum4me-mcp with three docs-tools requires schema work in the MCP repo and a coordinated release with this repo. docs/obsidian-authoring.md must be updated to reflect that the MCP now exposes docs.
  • Docs reads through MCP add a small latency and serialization step compared to direct file reads; acceptable because docs are small and rarely fetched per turn.

Confirmation

Implementation plan: docs/plans/M12-three-phase-feature-pipeline.md. Open implementation choices that were resolved while drafting the plan and are recorded here for traceability:

  • Worker authentication. Workers run under a dedicated service-account user with role agent_writer. The account is provisioned per environment (seed) and bound to the ClaudeBrainstorm.created_by for audit. This avoids granting personal user-credentials to background processes and gives demo-block + access-checks a single subject to reason about.
  • Brainstorm Q&A schema. Brainstorm questions live in a new ClaudeBrainstormQuestion table linked to ClaudeBrainstorm, parallel to M11's ClaudeQuestion (which stays story-bound). Avoids retrofitting M11 with optional story_id.
  • Plan templates. Canonical plan-templates live under docs/plans/templates/ (milestone.md, story.md) so fase 2 produces reproducibly-shaped plans.
  • Headless preview. An in-app <DraftPreview /> shipped in v1 alongside the obsidian://-link, so Cowork-only users can review without an Obsidian install.

The pipeline is considered working when a user can submit an idea on a product page, complete a grill-me dialogue inside the app, review the resulting draft in-app or in Obsidian, trigger fase 2, see PBI/Story/Task rows appear, and trigger fase 3 from the existing "Voer uit"-knop without any manual file editing in between.