feat(process): integrate agentic Agile methodology

.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
+
+<!-- Describe the unexpected behaviour. -->
+
+## Contract Violated
+
+<!-- Which contract, interface method, or postcondition was broken? -->
+
+```go
+// Postcondition / invariant that was violated:
+```
+
+## Steps to Reproduce
+
+1.
+2.
+3.
+
+## Expected Behaviour
+
+<!-- What the contract guarantees. -->
+
+## Actual Behaviour
+
+<!-- What actually happened. Paste error output if available. -->
+
+## Environment
+
+| Field | Value |
+|-------|-------|
+| OS | |
+| Arch | |
+| `devops-starter` version | |
+| Config file path | |
+
+## Logs / Output
+
+```
+paste output here
+```
+
+## Notes
+
+<!-- Workaround, related issues, suspected cause. -->

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.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
+
+<!-- What this epic delivers end-to-end. One paragraph. -->
+
+## Child Spec Issues
+
+<!-- Create a spec issue for each work stream before implementation begins. -->
+
+- [ ] #<!-- spec -->
+- [ ] #<!-- spec -->
+
+## 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
+
+<!-- Architecture decisions, constraints, external dependencies. -->

.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
+
+<!-- One-sentence description of the capability. -->
+
+## Motivation
+
+<!-- Why does this matter? What problem does it solve? -->
+
+## Contract
+
+### Public Types
+
+<!-- New or modified types in pkg/tooldef/ or exported interfaces in internal/cli/deps.go. -->
+
+```go
+// TODO: define types / interface changes
+```
+
+### YAML Schema
+
+<!-- New or modified fields in configs/default.yaml. Leave blank if no config changes. -->
+
+```yaml
+# TODO: schema snippet
+```
+
+### CLI Interface
+
+<!-- New subcommand, flags, or output format changes. Leave blank if no CLI changes. -->
+
+```
+devops-starter <subcommand> [flags]
+```
+
+## Acceptance Criteria
+
+- [ ] <!-- criterion 1 -->
+- [ ] <!-- criterion 2 -->
+- [ ] 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)
+
+- [ ] <!-- task A -->
+- [ ] <!-- task B -->
+
+### Wave 3 — Integration
+
+- [ ] Wire CLI command(s)
+- [ ] Update config / state if schema changed
+
+### Wave 4 — Validation
+
+- [ ] All acceptance criteria checked
+- [ ] README / docs updated
+
+## Notes
+
+<!-- Constraints, open questions, links to related issues or ADRs. -->

.github/pull_request_template.md

@@ -0,0 +1,30 @@
+## Summary
+
+<!-- What does this PR do and why? -->
+
+Closes #<!-- spec / bug issue number -->
+
+## 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: <!-- platform(s) -->

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

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 |