A-SDLC: Automated Agentic Software Development Lifecycle

Start here: docs/agentic-workflow-explained.md — the full flow with diagrams, and a real worked example (kirti/a-sdlc-bookmark-manager) showing every stage's actual output, not a hypothetical.

A complete, runnable reference implementation of the 12-stage agentic SDLC pipeline (see docs/diagram-mapping.md for the box-by-box mapping to the original design). Includes a real end-to-end test: the pipeline drafts requirements, gets them approved, designs an architecture, generates coding rules, plans tasks, writes real source code, reviews it, tests it, security-scans it, generates a CI/CD workflow, runs the generated app to produce real monitoring data, and proposes rule updates for the next run.

This has been run end-to-end and verified — see docs/verified-run-log.md for the full console output of a real run, and sdlc/ + target-app/ for the actual artifacts it produced (this is not a description of what it would do; it's what it did).

Project layout

a-sdlc/
├── orchestrator/           Kotlin orchestrator - all 12 agent stages + CLI
├── sdlc-refinement/        Claude Skill (requirements.md → implementation.md → agent.md)
├── sdlc/                   Artifact store: requirements, implementation, plans, reports
├── target-app/             The generated deliverable: Product Catalog CRUD (this run's output)
├── business-templates/     Raw business requests (Stage 1 input)
├── .github/workflows/      5 workflows, each boundary = a human gate
└── docs/
    ├── diagram-mapping.md      Every original diagram box → its implementing file
    └── verified-run-log.md     Full console output of the real end-to-end run

Why zero external dependencies

The orchestrator (orchestrator/) is written to compile with zero Maven artifacts beyond the Kotlin standard library — hand-rolled JSON (util/Json.kt), java.net.http for the Claude API client, no CLI-parsing library. This was a deliberate constraint, not a limitation: it means the orchestrator can be verified with plain kotlinc in any environment (including ones without Maven Central access, which is how this reference build was actually compiled and tested), while still shipping as a normal Gradle project (build.gradle.kts/settings.gradle.kts included) for CI environments where Maven Central is reachable.

Mock vs. Real LLM provider

Every agent that needs LLM reasoning (Refinement, Design, Planning, Review, Learning) goes through the LlmClient interface (orchestrator/src/main/kotlin/asdlc/client/LlmClient.kt):

• MockClaudeClient (default): deterministic, canned-but-realistic responses keyed to this specific business template. Used for the verified local run — no network or API key required. This is what proves the pipeline mechanics (handoffs, gates, schemas, retry structure) work correctly, independent of any specific LLM call.
• RealClaudeClient: calls the real Anthropic API (/v1/messages). Activate with:

  export ASDLC_LLM_PROVIDER=real
  export ANTHROPIC_API_KEY=sk-ant-...

The Testing, Security, and Coding-via-Claude-Code paths are not mocked — they either run real deterministic logic (compiling and executing the generated Kotlin code, regex-based secret/SAST scanning) or shell out to the real claude CLI in production mode (RealCodingBackend). Only the "reasoning" calls have a mock path.

Testing this on real GitHub Actions (not just locally)

See docs/testing-the-agentic-cicd.md for a full step-by-step runbook: one-time repo setup (secrets, permissions, branch protection, Environments), how to trigger the chain, and — critically — how to confirm the deploy gates actually pause for approval rather than just looking correct in the YAML. Testing is free and safe by default: every workflow uses a mock LLM provider unless you explicitly set the ASDLC_LLM_PROVIDER repo variable to real.

Both orchestrator/ and target-app/ include a real Gradle wrapper (gradlew, gradle/wrapper/), so ./gradlew build/run work out of the box in CI or on your machine — no separate Gradle install needed. (This sandbox couldn't fully execute ./gradlew itself since it has no access to services.gradle.org; the wrapper's bootstrap jar and scripts were verified as genuine, and the failure was confirmed to be exactly the network block, not a broken wrapper — a real runner will succeed here.)

Running it

Full pipeline, one command (local test mode, all gates auto-approved)

cd orchestrator
kotlinc src/main/kotlin/asdlc/**/*.kt -include-runtime -d asdlc.jar
cd ..
ASDLC_PROJECT_ROOT=$(pwd) java -cp orchestrator/asdlc.jar asdlc.MainKt run-all --id CRUD-001

(With Gradle, once you're in an environment with Maven Central access: cd orchestrator && ./gradlew run --args="run-all --id CRUD-001".)

Stage by stage (matches production GitHub Actions flow)

asdlc intake --id CRUD-001
asdlc refine --id CRUD-001
# --- human reviews sdlc/requirements/CRUD-001.md, then: ---
asdlc approve-requirements --id CRUD-001
asdlc design --id CRUD-001
asdlc generate-agent-md --id CRUD-001 --project-name "My Project"
asdlc plan --id CRUD-001
# --- human reviews sdlc/implementation/CRUD-001.md, then merges the PR, then: ---
asdlc execute-tasks --id CRUD-001   # Stages 6-9: Coding -> Review -> Testing -> Security, with retry loop
# --- human reviews generated code + test/security reports, then merges the PR, then: ---
asdlc generate-cicd --id CRUD-001   # Stage 10: writes target-app's own build/deploy workflow

Running the generated CRUD app's tests directly

cd target-app
kotlinc src/main/kotlin/crud/util/Json.kt src/main/kotlin/crud/Product.kt \
        src/main/kotlin/crud/ProductRepository.kt src/main/kotlin/crud/ProductService.kt \
        -include-runtime -d main.jar
kotlinc -cp main.jar src/test/kotlin/crud/ProductServiceTest.kt -include-runtime -d test.jar
java -cp "main.jar:test.jar" crud.ProductServiceTest

Expected output: TEST_SUMMARY: 10/10.

Human gates — where they really are

Gate	Enforced by
Requirements approval	Code-level: ArchitectureDesignAgent throws if status != APPROVED. Production: PR merge.
Implementation plan approval	Production: PR merge (workflow 2→3).
PR / deploy authorization	Production: PR merge (workflow 3→4) + GitHub environment: protection on the generated deploy-canary/deploy-production jobs.

Local run-all auto-approves every gate — loudly, with a labeled banner — so the full chain is testable in one command. This is clearly not how gates work in production; see .github/workflows/ for the real mechanism.

What's a deliberate reference-implementation simplification

See the "What's deliberately a reference implementation" section at the bottom of docs/diagram-mapping.md for the full list (License Check, full OWASP validation, Cost monitoring, Docker packaging, and the review→coding retry loop are modeled in the data types but not fully wired). Nothing from the original diagram was silently dropped — every box maps to either a working implementation or an explicit note on why it's out of scope for this reference build and how to extend it.

The sdlc-refinement Claude Skill

sdlc-refinement/ is a portable Claude Skill (Claude Code primary, Claude API supported) implementing the full agentic SDLC flow end-to-end: change detection (update vs. greenfield), context intake across 6 source types, requirement refinement, tech stack ID with scaffold cloning, architecture design with an always-on HTTP layer and Postman collection, agent.md maintenance, stack-agnostic planning, coding with a full execution log, and — critically — four independent pre-push verification gates (code-reviewer on Opus, test-runner and security-scanner and api-tester on Haiku, each a real Claude Code subagent in sdlc-refinement/claude-agents/), plus CI/CD (build → test → Newman → Docker → ghcr.io → deploy-hook-gated release), monitoring, and continuous learning.

Install with ./install-skill.sh (personal or --project scope) — it installs both the skill and the four subagents, verified end-to-end against a fake $HOME covering every flag combination (default, decline-overwrite, --force, --project, --skip-agents, bad --source).

See sdlc-refinement/SKILL.md for the full stage-by-stage design.