From be6b7229dad307763663801cdeac44ca2e598423 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 3 Jun 2026 18:32:36 +0000 Subject: [PATCH] feat(process): integrate Agentic Agile methodology Adds Agentic Agile practices on top of the existing CDD workflow, inspired by the Microsoft Developer Blog article on spec-first, wave-based agent collaboration. - docs/agentic-agile.md: full methodology reference (4 pillars, wave diagram, iterative partnership model, quick reference table) - CLAUDE.md: new "Agentic Agile Development" section with workflow summary and issue label reference - .github/ISSUE_TEMPLATE/spec.md: spec-first feature template with contract, acceptance criteria, and Wave 1-4 implementation phases - .github/ISSUE_TEMPLATE/epic.md: epic template with wave/stream table and review-gate checklist for agent swarming - .github/ISSUE_TEMPLATE/bug.md: bug report framed around contract violations with environment and reproduction steps - .github/ISSUE_TEMPLATE/config.yml: disables blank issues, enforcing template selection - .github/pull_request_template.md: combined CDD + Agentic Agile checklist (spec link, phase complete, review gate respected) - .github/workflows/retrospective.yml: manual workflow_dispatch that collects commits, merged PRs, and closed issues for a sprint window, then files a structured retrospective GitHub issue https://claude.ai/code/session_01U2MguaxzBYvrRyhNQoubfj --- .github/ISSUE_TEMPLATE/bug.md | 52 +++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 1 + .github/ISSUE_TEMPLATE/epic.md | 59 +++++++++++++++ .github/ISSUE_TEMPLATE/spec.md | 77 +++++++++++++++++++ .github/pull_request_template.md | 30 ++++++++ .github/workflows/retrospective.yml | 96 ++++++++++++++++++++++++ CLAUDE.md | 20 +++++ docs/agentic-agile.md | 110 ++++++++++++++++++++++++++++ 8 files changed, 445 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug.md create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/epic.md create mode 100644 .github/ISSUE_TEMPLATE/spec.md create mode 100644 .github/pull_request_template.md create mode 100644 .github/workflows/retrospective.yml create mode 100644 docs/agentic-agile.md diff --git a/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.md new file mode 100644 index 0000000..3db063e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.md @@ -0,0 +1,52 @@ +--- +name: Bug Report +about: Contract violation or unexpected behaviour +title: "bug: " +labels: [bug] +assignees: [] +--- + +## What Happened + + + +## Contract Violated + + + +```go +// Postcondition / invariant that was violated: +``` + +## Steps to Reproduce + +1. +2. +3. + +## Expected Behaviour + + + +## Actual Behaviour + + + +## Environment + +| Field | Value | +|-------|-------| +| OS | | +| Arch | | +| `devops-starter` version | | +| Config file path | | + +## Logs / Output + +``` +paste output here +``` + +## Notes + + diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..3ba13e0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: false diff --git a/.github/ISSUE_TEMPLATE/epic.md b/.github/ISSUE_TEMPLATE/epic.md new file mode 100644 index 0000000..d4bd57c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/epic.md @@ -0,0 +1,59 @@ +--- +name: Epic +about: Large capability decomposed into child spec issues and agent work streams +title: "epic: " +labels: [epic] +assignees: [] +--- + +## Goal + + + +## Child Spec Issues + + + +- [ ] # +- [ ] # + +## Agent Work Streams + +> Streams within the same wave can run in parallel. No Wave N+1 work begins until Wave N is reviewed and merged. + +### Wave 1 — Contracts & Schema (sequential) + +| Stream | Owner | Spec issue | +|--------|-------|------------| +| Public types | | | +| YAML / config schema | | | +| CLI skeleton | | | + +### Wave 2 — Core Implementation (parallel) + +| Stream | Owner | Spec issue | +|--------|-------|------------| +| | | | +| | | | + +### Wave 3 — Integration & Docs (sequential) + +| Stream | Owner | Spec issue | +|--------|-------|------------| +| | | | + +## Review Gates + +- [ ] Wave 1 reviewed and merged before Wave 2 begins +- [ ] Wave 2 integration test passes before Wave 3 begins + +## Definition of Done + +- [ ] All child spec issues closed +- [ ] End-to-end acceptance test passes +- [ ] `ARCHITECTURE.md` updated if design decisions changed +- [ ] No regressions in `make check` + +## Notes + + diff --git a/.github/ISSUE_TEMPLATE/spec.md b/.github/ISSUE_TEMPLATE/spec.md new file mode 100644 index 0000000..5c290ca --- /dev/null +++ b/.github/ISSUE_TEMPLATE/spec.md @@ -0,0 +1,77 @@ +--- +name: Feature Spec +about: Spec-first feature definition — contract before code +title: "spec: " +labels: [spec] +assignees: [] +--- + +## Summary + + + +## Motivation + + + +## Contract + +### Public Types + + + +```go +// TODO: define types / interface changes +``` + +### YAML Schema + + + +```yaml +# TODO: schema snippet +``` + +### CLI Interface + + + +``` +devops-starter [flags] +``` + +## Acceptance Criteria + +- [ ] +- [ ] +- [ ] Contract tests pass: preconditions, postconditions, and invariants verified +- [ ] `make check` passes (fmt + vet + lint + test) + +## Implementation Phases + +> Break into waves for agent swarming. Each wave can be parallelised; review gates between waves. + +### Wave 1 — Foundation (sequential, review gate before Wave 2) + +- [ ] Define public types / constants +- [ ] Write contract tests (red → green) +- [ ] Update YAML schema and bump `ConfigVersion` if needed + +### Wave 2 — Implementation (can be parallelised) + +- [ ] +- [ ] + +### Wave 3 — Integration + +- [ ] Wire CLI command(s) +- [ ] Update config / state if schema changed + +### Wave 4 — Validation + +- [ ] All acceptance criteria checked +- [ ] README / docs updated + +## Notes + + diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..bb243ea --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,30 @@ +## Summary + + + +Closes # + +## Changes + +- + +## Contract-Driven Development + +- [ ] **Spec first** — a spec or bug issue is linked above and was opened before implementation +- [ ] **Contract defined** — public types in `pkg/tooldef/` or interface docs in `internal/cli/deps.go` updated +- [ ] **Contract tests** — pre/postconditions and invariants tested, not just happy path +- [ ] **Error handling** — contract violations produce a clear error or `panic`, not silent failure +- [ ] **Config version** — bumped `ConfigVersion` if config schema changed, migration provided +- [ ] **State version** — bumped `StateVersion` if state schema changed, migration provided + +## Agentic Agile + +- [ ] **Phase complete** — this PR closes one or more waves defined in the linked spec issue +- [ ] **No spec drift** — implementation matches the contract in the spec; spec updated if requirements changed +- [ ] **Review gate respected** — if this closes Wave 1 or Wave 2, the next wave has not been started + +## Test Plan + +- [ ] `make test` passes +- [ ] `make lint` passes +- [ ] Tested on: diff --git a/.github/workflows/retrospective.yml b/.github/workflows/retrospective.yml new file mode 100644 index 0000000..46b19f4 --- /dev/null +++ b/.github/workflows/retrospective.yml @@ -0,0 +1,96 @@ +name: Sprint Retrospective + +on: + workflow_dispatch: + inputs: + sprint_name: + description: Sprint name (e.g. "Sprint 3 – June 2026") + required: true + type: string + since: + description: Sprint start date (YYYY-MM-DD) + required: true + type: string + until: + description: Sprint end date (YYYY-MM-DD, defaults to today) + required: false + type: string + default: "" + +permissions: + contents: read + issues: write + +jobs: + retrospective: + name: Generate Sprint Retrospective + runs-on: ubuntu-latest + env: + GH_TOKEN: ${{ github.token }} + steps: + - uses: actions/checkout@v5 + with: + fetch-depth: 0 + + - name: Ensure retrospective label exists + run: gh label create retrospective --color 0075ca --description "Sprint retrospective report" --force + + - name: Generate and file retrospective + env: + SPRINT_NAME: ${{ inputs.sprint_name }} + SINCE: ${{ inputs.since }} + UNTIL_INPUT: ${{ inputs.until }} + run: | + UNTIL="${UNTIL_INPUT:-$(date +%Y-%m-%d)}" + RETRO="$(mktemp)" + + # Header + printf '# Retrospective: %s\n\n**Period:** %s -> %s \n**Generated:** %s\n\n---\n\n' \ + "$SPRINT_NAME" "$SINCE" "$UNTIL" "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" >> "$RETRO" + + # Commit activity + COMMIT_COUNT=$(git log --oneline --after="$SINCE" --before="$UNTIL 23:59:59" 2>/dev/null | wc -l | tr -d ' ') + printf '## Commit Activity\n\nTotal: **%s commits**\n\n' "$COMMIT_COUNT" >> "$RETRO" + git log --after="$SINCE" --before="$UNTIL 23:59:59" \ + --pretty="format:- \`%h\` %s" >> "$RETRO" 2>/dev/null || true + printf '\n\n' >> "$RETRO" + + # Merged pull requests + printf '## Merged Pull Requests\n\n' >> "$RETRO" + gh pr list --state merged \ + --search "merged:${SINCE}..${UNTIL}" \ + --json number,title,url,author \ + --jq '.[] | "- [\(.title)](\(.url)) — @\(.author.login)"' \ + >> "$RETRO" 2>/dev/null || printf '- None\n' >> "$RETRO" + printf '\n' >> "$RETRO" + + # Closed issues bucketed by label + printf '## Closed Issues\n\n' >> "$RETRO" + for label in spec epic bug; do + ITEMS=$(gh issue list --state closed \ + --label "$label" \ + --search "closed:${SINCE}..${UNTIL}" \ + --json number,title,url \ + --jq '.[] | "- [\(.title)](\(.url))"' 2>/dev/null || true) + if [[ -n "$ITEMS" ]]; then + LABEL_UPPER="${label^}" + printf '### %s\n\n%s\n\n' "$LABEL_UPPER" "$ITEMS" >> "$RETRO" + fi + done + + # Retrospective prompts (static section) + printf '%s\n' "---" >> "$RETRO" + printf '\n## Team Retrospective\n\n' >> "$RETRO" + printf '> Fill in this section collaboratively or in an agent-assisted review session.\n\n' >> "$RETRO" + for section in "What went well?" "What could be improved?" "Contract violations discovered" "Carry-over to next sprint" "Process / tooling changes for next sprint"; do + printf '### %s\n\n-\n\n' "$section" >> "$RETRO" + done + printf '---\n\n' >> "$RETRO" + printf '*Generated by the [retrospective workflow](../../.github/workflows/retrospective.yml).* \n' >> "$RETRO" + printf '*Methodology: [Agentic Agile](../../docs/agentic-agile.md)*\n' >> "$RETRO" + + # Create the retrospective issue + gh issue create \ + --title "Retrospective: ${SPRINT_NAME}" \ + --label retrospective \ + --body-file "$RETRO" diff --git a/CLAUDE.md b/CLAUDE.md index bda9438..f5f66ba 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -143,6 +143,26 @@ Table-driven test rows must name the contract being exercised, not just the inpu {"tool1", ...} // avoid ``` +## Agentic Agile Development + +This repo follows [Agentic Agile](docs/agentic-agile.md) — Agile practices adapted for teams where AI agents are active contributors. See `docs/agentic-agile.md` for the full methodology. + +### Workflow at a glance + +1. **Spec first** — open a GitHub issue using the **Feature Spec** template and fill in the contract section before writing any code. PRs must reference a spec issue. +2. **Phases** — the spec defines implementation waves. Do not start Wave 2 (parallel implementation) until Wave 1 (contracts, types, schema) is reviewed and merged. +3. **Epics** — large features use the **Epic** template to decompose work into parallel agent streams with review gates between waves. +4. **Retrospective** — at sprint end, run the `retrospective` workflow from GitHub Actions to auto-generate a report issue. + +### Issue labels + +| Label | When to use | +|-------|-------------| +| `spec` | New feature with a defined contract | +| `epic` | Multi-spec feature decomposed into waves | +| `bug` | Contract violation with reproduction steps | +| `retrospective` | Auto-generated sprint retrospective report | + ## Adding Tools / Groups / Commands | Task | Action | diff --git a/docs/agentic-agile.md b/docs/agentic-agile.md new file mode 100644 index 0000000..7661849 --- /dev/null +++ b/docs/agentic-agile.md @@ -0,0 +1,110 @@ +# Agentic Agile: Development Methodology + +`devops-starter` follows an **Agentic Agile** methodology — Agile practices adapted for teams where AI agents are active contributors alongside humans. + +Inspired by the [Microsoft Developer Blog article on Agentic-Agile](https://developer.microsoft.com/blog/agentic-agile-why-agent-development-needs-agile-not-just-prompts), this document describes how the methodology applies in this repository. + +--- + +## Core Insight + +Prompt-driven development works for bounded tasks: generate a function, refactor a module, write a test. Larger features require the same alignment mechanisms that Agile brought to human teams — spec clarity, iterative delivery, retrospection — adapted to the pace and capabilities of agents. + +The existing [Contract-Driven Development](../CLAUDE.md#contract-oriented-development) practices form the technical foundation. Agentic Agile adds the *process* layer on top. + +--- + +## The Four Pillars + +### 1. Spec First + +Every feature or fix starts as a GitHub issue **before any code is written**. The spec defines: + +- The **contract**: new public types, YAML schema snippets, CLI interface changes +- **Acceptance criteria** as checkboxes +- **Implementation phases** for agent swarming (see below) + +Agents must not implement a feature that lacks a linked spec issue. This prevents _spec drift_ — design docs updated by agents diverging from original specs, causing confusion in multi-agent swarms. + +**Template:** [Feature Spec](.github/ISSUE_TEMPLATE/spec.md) + +### 2. Issue-Based Backlog + +The GitHub issue tracker is the single source of truth for all planned work: + +| Label | Template | Purpose | +|-------|----------|---------| +| `spec` | Feature Spec | Single feature with contract and acceptance criteria | +| `epic` | Epic | Large capability decomposed into child spec issues | +| `bug` | Bug Report | Contract violation with reproduction steps | +| `retrospective` | _(generated)_ | Sprint retrospective auto-generated by workflow | + +Every PR must reference a spec or bug issue. The PR template enforces this. + +### 3. Epic Decomposition for Agent Swarming + +Large features are broken into **waves** that define which work can be parallelised across agents: + +``` +Wave 1 (Foundation) Wave 2 (Implementation) Wave 3 (Integration) + Sequential Can be parallelised Sequential + ───────────────── ──────────────────────── ───────────────── + Public types → Agent A: installer changes → CLI wiring + Schema changes gate Agent B: registry changes gate Config / state + Contract tests Agent C: TUI changes Docs update +``` + +Review gates occur between waves. Wave 1 must be reviewed and merged before Wave 2 begins — this prevents type-level conflicts when multiple agents modify shared code in parallel. + +**Template:** [Epic](.github/ISSUE_TEMPLATE/epic.md) + +### 4. Sprint Retrospectives + +At the end of each sprint, run the **retrospective workflow**: + +1. Go to **Actions → Sprint Retrospective → Run workflow** +2. Enter the sprint name and date range +3. The workflow collects merged PRs, closed issues, and commit history +4. A structured retrospective is filed as a GitHub issue labelled `retrospective` +5. Fill in the qualitative prompts (what went well, what to improve, carry-overs) + +**Workflow:** [`.github/workflows/retrospective.yml`](.github/workflows/retrospective.yml) + +--- + +## Agent Context Files + +The repo keeps agent instructions in sync via symlinks: + +| File | Purpose | +|------|---------| +| `CLAUDE.md` | Primary instructions — architecture, contracts, commands | +| `AGENTS.md` | Symlink → `CLAUDE.md` (read by Codex and other agents) | +| `.github/copilot-instructions.md` | Symlink → `CLAUDE.md` (read by GitHub Copilot) | + +`CLAUDE.md` is the single source of truth. Edit only `CLAUDE.md`; the symlinks propagate automatically. + +--- + +## Iterative Partnership Model + +Agent sessions evolve through recognisable phases: + +| Phase | Description | +|-------|-------------| +| **Design & handoff** | Human writes the spec issue; agent reads it and asks clarifying questions before coding | +| **Alternating layers** | Human reviews Wave 1 output; agent implements Wave 2; human reviews; etc. | +| **Parallel swarming** | Multiple agent sessions work on independent Wave 2 streams simultaneously | +| **Retrospective** | Workflow generates a report issue; human or agent fills in qualitative prompts | + +--- + +## Quick Reference + +| Action | How | +|--------|-----| +| Start a new feature | Open a **Feature Spec** issue; fill in the contract and phases before coding | +| Plan a large feature | Open an **Epic** issue; decompose into child spec issues | +| Report a bug | Open a **Bug Report** issue; identify the violated contract | +| Submit code | Open a PR referencing the spec/bug issue; check both CDD and Agentic Agile items | +| End of sprint | Run the **Sprint Retrospective** workflow from GitHub Actions |