L1DDER — Development Methodology

Philosophy: The AI agent handles execution mechanics and self-verification. The human owns intent, priorities, and quality acceptance. Core Invariant: The Roadmap (docs/roadmap.md) is the Single Source of Truth. Nothing is built outside the Roadmap (except /l1-hotfix for urgent bugs, /l1-chore for changes to the project itself, and /l1-fast — strictly human-invoked for a small product feature while position 1 (CURRENT) is empty).

L1DDER defines a closed-loop Spec-driven development lifecycle with AI coding agents: from onboarding (/l1-onboard) and raw ideas in the Idea Bank (/l1-idea) to specifications in the Backlog (/l1-feature), scheduling in the Roadmap (/l1-planning), step-by-step sprint execution (/l1-task), and mandatory sprint hygiene (Doctor Checklist) at the end of every sprint.

---

1. Map of L1DDER Artifacts & Flows

---

2. Project Foundation (docs/concept/)

Created once at project start (via /l1-onboard) and mandatorily kept up to date at the end of every sprint (during the Doctor Checklist task):

Document	Template	Required	Condition
idea.md	idea-template.md	Required	Always (high-level product essence & MVP)
vision.md	vision-template.md	Required	Always (technical vision, roles, stack)
architecture.md	architecture-template.md	Required	When ≥2 components / layers exist
data-model.md	data-model-template.md	Required	When DB, local store, or config schemas exist
integrations.md	integrations-template.md	Required	When external services / SDKs exist
api-contracts.md	api-contracts-template.md	Optional	When HTTP/RPC or module contracts exist
ADR in adrs/	adr-template.md	As needed	For significant architectural decisions

---

3. Core Workflows

Flow 0: Project Onboarding (/l1-onboard)

The single entry point after npx l1dder init. It runs six stages, one file each, and waits for "ok" at each:

1. Detects from-scratch or existing-code mode and the first unfinished stage. In existing-code mode the code is the primary source of facts.
2. Works out the concept: docs/concept/idea.md → vision.md → architecture.md (plus integrations.md and api-contracts.md if needed) → data-model.md. Each stage runs rounds of up to 7 questions with recommendations and the question "Move on or another round?".
3. Derives the stack from the architecture: l1dder/rules/30-tech-stack.mdc, 40-skills-router.mdc, Makefile, then runs npx l1dder sync.
4. Creates docs/ideas.md, docs/backlog.md, docs/roadmap.md, and docs/README.md.

Flow 1: Idea Flow (/l1-idea → docs/ideas.md)

1. Invoked via /l1-idea.
2. Agent checks docs/ideas.md for duplicates, asks decision-tree questions (grilling: ❓ Q1 ➡️ Recommendation), and trims bloat via ponytail.
3. After "ok", records IDEA-NNN in docs/ideas.md with priority (P0..P3) and status 📋 unrealized.

Flow 2: Feature & Spec Flow (/l1-feature → docs/specs/ + docs/backlog.md)

1. Invoked via /l1-feature for an IDEA-NNN.
2. Drafts docs/specs/FEAT-NNN-<slug>/{requirements,design,tasks}.md with Deep Modules (codebase-design), Pre-agreed Test Seams (tdd), and step candidates FEAT-NNN.01 .. FEAT-NNN.99 (where .99 is always the mandatory Doctor Checklist).
3. After "ok", writes the spec, adds FEAT-NNN to docs/backlog.md (📋 in-backlog), and sets IDEA-NNN to 🚧 in-progress.

Flow 3: Planning Flow (/l1-planning → docs/roadmap.md)

1. Invoked via /l1-planning.
2. Proposes the Delivery Queue (sprints SPRINT-NN) and Discovery Queue (ideas IDEA-NNN).
3. After "ok", updates docs/roadmap.md, assigns SPRINT-NN and TASK-NN.01..99 in docs/backlog.md (🗓 scheduled), and creates docs/sprints/SPRINT-NN-<slug>/README.md.
4. Rejecting the current sprint: if the team decides to abandon the active sprint at 1 (CURRENT), /l1-planning shows its commits and uncommitted changes (⛔ STOP), and after "ok" rolls back the code with git revert without rewriting history, keeps the sprint and task documents as a record with status ❌ rejected, and frees 1 (CURRENT).

Flow 4: Task & Sprint Hygiene Flow (/l1-task)

• Regular tasks (TASK-NN.01 .. TASK-NN.K) follow the Two-Approval Rule:
  1. Plan (plan.md) → ⛔ STOP #1 (wait for "ok").
  2. Implement (strictly within Scope, Edit → Sanitize → Verify, vertical TDD at seams).
  3. Self-check (DoD commands + ponytail-review) → ⛔ STOP #2 (DoD table + 2-line Ponytail skipped / Risk footer, wait for "ok").
  4. Confirm & Record (summary.md + status sync across 4 files).
• Mandatory final sprint task (TASK-NN.99 — Doctor Checklist):
  1. Code & Repo Doctor (make ci + 2-axis code-review + ponytail-audit + ponytail-debt).
  2. Agent E2E Verification (make test-e2e + live scenario walk-through).
  3. Living Docs Sync + retro (mandatory update of docs/concept/*, docs/specs/*, docs/adrs/*, and l1dder/rules/*.mdc).
  4. Human UAT (step-by-step manual test guide for the human at ⛔ STOP #2, followed by cascading closure TASK-NN.99 ✅ → SPRINT-NN ✅ → FEAT-NNN ✅ → IDEA-NNN ✅).

Flow 5: Hotfix Exception (/l1-hotfix)

Reproduces an urgent bug first (RED Gate — diagnosing-bugs), gets "ok" on a concise chat plan, applies the minimal fix (GREEN + make ci), and logs HOTFIX-NNN in docs/backlog.md.

Flow 6: Chore Exception — Changes to the Project Itself (/l1-chore)

For changes to the project itself, not to what its users see: git rules (branch and commit names, pre-push checks), automatic checks in CI, library updates, the Makefile, build scripts, tests, rules for the AI agent. No idea, spec or sprint: the agent checks that the product stays unchanged (otherwise it changes no files and suggests /l1-task or /l1-hotfix), computes CHORE-NNN, gets a single "ok" on the options, makes the minimal change (make ci), and logs CHORE-NNN in the Chore Log of docs/backlog.md (adding the section if it is missing).

Flow 7: Fast Mode Exception for a Small Feature (/l1-fast)

For a small product feature (up to three tasks in one sprint, with no new data model, external integration, ADR, or breaking changes) while position 1 (CURRENT) in docs/roadmap.md is empty. This command is strictly human-invoked — the agent is forbidden from running /l1-fast on its own initiative. If 1 (CURRENT) is occupied by a regular sprint, /l1-fast refuses without changing any file and points to /l1-task or sprint rejection via /l1-planning. Otherwise the agent clarifies via grilling, checks four size signs, and stops at ⛔ STOP #1 ("ok"), reserves IDEA-NNN, FEAT-NNN, SPRINT-NN at 1 (CURRENT) marked mode: /l1-fast, implements via TDD slices (committing each finished task), runs every check from the regular flow and TASK-NN.99 (make ci, ponytail-review, two-axis code-review, ponytail-audit, ponytail-debt, E2E, docs sync, and retro), stops at ⛔ STOP #2 for manual testing ("ok"), and then records the full registry chain with | **Mode** | \/l1-fast` |` in every document passport.

Flow 8: Meta Loop — Evolution & Dogfooding (/l1-evo → l1dder/evolution/)

L1DDER evolves by 100% dogfooding following l1dder/evolution/METHODOLOGY-RULES.md, logging in WORKLOG-CHANGELOG.md, and updating HANDOFF.md.