AI-Assisted Software Development Life Cycle (AI-SDLC)
Comprehensive canonical documentation for the AI-Assisted Software Development Life Cycle used in the FHNW BSc Business Artificial Intelligence module.
Reading this guide
AI-SDLC organizes a change around a simple question: what must be true before another person or agent can continue the work? A specification captures the intended behavior, project documentation records technical context, and tests provide evidence about the implementation.
Read the lifecycle first, then the worked example. The artifact sections explain where the results belong. This page distinguishes the intended method from the starter implementation: instructions are not an automated lifecycle engine, and an example is not evidence of measured effectiveness.
AI-SDLC — September 2026. The repository instructions now include a scoped Fast Track, on-demand architecture decision records (ADRs) in DESIGN, and reviewed feedback of accepted decisions into agent instructions. These are human/agent procedures, not automated enforcement.
Overview
The AI-Assisted Software Development Life Cycle (AI-SDLC) is a lightweight, spec-driven lifecycle for governed agentic software engineering. “Lean” and “spec-driven” describe the approach; they are not additional words in the expansion of AI-SDLC. It supports collaboration between human developers and AI coding agents such as GitHub Copilot, Cline, Claude Code, Codex, Cursor, Windsurf or comparable tools.
The method integrates:
Test-Driven Development (TDD) and the testing pyramid
Clean Architecture and explicit dependency boundaries
Continuous Integration and Continuous Delivery (CI/CD)
Containerized releases where the selected technology stack benefits from them
Lean Spec-Driven Development (SDD) orchestrated by
AGENTS.mdand phase-specificskills/ai-sdlc-[phase]SAFe-compatible iterative delivery
Kanban-based execution using GitHub Projects
The method is repository-centred. Project knowledge, current state, use-case specifications, architecture decisions and agent instructions remain close to the code so that they can be inspected, versioned and reviewed together.
Visual Overview
The lifecycle is iterative. A failed quality gate is evidence for another development or specification cycle, not a reason to bypass validation.
Phase Summary
0 BOOTSTRAP
What project are we building?
Working project context
1 SPECIFY
What must the change do?
Testable acceptance criteria
2 DESIGN
Where does behavior belong?
Boundaries and necessary decisions
3 DEVELOP
Does implementation satisfy the tests?
Tests and code
4 VALIDATE
What evidence supports readiness?
Verified checks and artifact evidence
5 DEPLOY
Is delivery prepared or executed?
Workflow verification and, if run, delivery evidence
0. BOOTSTRAP
Initialize the project structure and establish the architecture baseline:
clarify the system or application purpose;
record language, framework and runtime;
inspect existing source, tests, dependency files and documentation;
establish compatible Clean Architecture boundaries;
document dependencies, commands and runtime assumptions;
prepare the context for the first use-case specification in SPECIFY;
complete
docs/PROJECT.md;record the initial state in
docs/TASKS.md.
BOOTSTRAP should adapt an existing repository where possible. It creates only missing structure and does not remove or restructure existing content without a clear decision.
1. SPECIFY
Turn one user story or change request into a single executable use-case specification in docs/specs/UC-XXX.md.
The specification records:
intent and business value;
actors and preconditions;
scope, including explicit IN and OUT boundaries;
the normal flow;
errors and exceptional cases;
acceptance criteria;
minimal non-functional requirements;
test-intent mapping for unit, integration and end-to-end tests.
“Executable specification” means precise enough to derive tests from; the Markdown itself is not runnable. The current template contains Intent, Actors, Preconditions, Flow, Errors, Acceptance and Tests. Scope and non-functional requirements can be recorded within those sections.
No implementation is generated during SPECIFY. The specification is the contract against which design, tests and implementation are reviewed.
2. DESIGN
Stabilize the architecture and boundaries for the current use case.
The team or agent:
reads the use-case specification and
docs/PROJECT.md;identifies the minimum required domain, application, interface and infrastructure components;
confirms frameworks, libraries, data stores and external integrations;
defines ports, adapters and dependency direction;
slices the work into small vertical tasks in
docs/TASKS.md;identifies the tests needed at each boundary.
The current DESIGN skill explicitly identifies components and updates docs/PROJECT.md if needed. Vertical task slicing is a recommendation from the original overview, but not an explicit output in that skill. Consequential architecture choices now require an on-demand ADR; ordinary implementation details do not. The DESIGN skill records alternatives and consequences, distinguishes proposed from accepted decisions, and links accepted decisions to current architecture and durable agent rules.
DESIGN does not implement code or generate tests. It produces a sufficiently precise plan for a small end-to-end slice.
3. DEVELOP
Implement the current use case using strict test-first development:
write or extend integration tests for boundary behavior;
write or extend unit tests for domain rules and use-case logic;
implement the smallest change that makes the tests pass;
refactor while preserving behavior;
review the result after each step and run the relevant local tests.
The working sequence is Red → Green → Refactor. Tests are derived from acceptance criteria and domain rules. Existing tests and source files should be extended before new files are created.
4. VALIDATE
Make the use case release-ready by checking the complete evidence chain:
unit tests;
integration tests;
end-to-end tests where the system has an end-to-end boundary;
build or packaging process;
Dockerfile and container execution where containerization is part of the project;
GitHub Actions CI;
release workflow and published artifact;
quality gates, such as a recommended coverage target of 80% or higher;
documentation of known limitations and configuration.
The current VALIDATE skill explicitly expects a Dockerfile, a container build, E2E tests and artifact publication. Its implementation is therefore container-oriented, even though the starter contains no application stack. Other delivery models require a deliberate project adaptation.
A configured project should run unit and integration tests on pull requests. End-to-end tests can run against a built container or another reproducible deployment artifact during release validation.
5. DEPLOY
The current skill verifies or collaboratively defines a deployment workflow. Completing it does not prove a deployment has run. Actual delivery needs a configured target, authorization and execution evidence.
Deploy only a validated artifact. The deployment workflow is defined together with the project owner and depends on the selected platform.
A CD workflow should document:
its trigger and approval model;
the artifact being deployed;
required environment variables and secret names;
the deployment target;
post-deployment smoke checks;
rollback or recovery expectations.
The template includes an inactive provider-neutral CD workflow skeleton. Configure .github/workflows/cd.yml during DEPLOY after the deployment target, required secrets and operational responsibilities have been decided.
Lean SDD (Spec-Driven Development)
Lean SDD is controlled by a small set of repository-local artifacts:
AGENTS.mdroutes the agent to the current lifecycle phase and defines guardrails;docs/TASKS.mddefines the current phase, active use case and backlog;docs/PROJECT.mdprovides project-specific architecture and runtime instructions;docs/specs/UC-XXX.mddefines the executable use-case contract;skills/ai-sdlc-[phase]provides phase-specific execution guidance.
At the beginning of a task, the agent loads the context in this order:
docs/TASKS.mddocs/PROJECT.mdthe active
docs/specs/UC-XXX.md, or the eligible Fast Track task entry when no specification appliesthe skill for the current phase
Phase and status
PHASE identifies the selected phase; STATUS describes progress within it. All six skills use the same convention, including BOOTSTRAP. Completion keeps the phase number; the next phase is selected explicitly, not automatically.
ready
Phase selected, work not started
in-progress
Phase being executed
done
Phase output verified
blocked
Cannot continue; record the reason
For example, completed BOOTSTRAP is PHASE: 0 / STATUS: done. Selecting SPECIFY changes this to PHASE: 1 / STATUS: ready. These are maintained records, not an enforced state machine.
done applies to the selected phase output. In DEPLOY, a verified workflow is not proof that an artifact was deployed. Record actual deployment evidence separately.
The router explicitly permits agents to maintain docs/TASKS.md. Changes to AGENTS.md require an explicitly approved rule change or human review before merge. An agent may propose a change but must not silently rewrite its own operating rules.
This separation keeps the method stable while allowing each project to record its own technology and domain context.
Artifacts
The primary workflow artifacts are repository-local:
AGENTS.md
Workflow router, context order and guardrails
docs/TASKS.md
Lifecycle state, active use case and backlog
docs/PROJECT.md
Purpose, architecture, structure, commands and dependencies
docs/specs/UC-XXX.md
Use-case intent, flow, errors, acceptance and test intent
skills/ai-sdlc-[phase]
Execution guidance for each lifecycle phase
docs/adr/ADR-NNN-short-title.md
On-demand architecture decisions, status and rationale
Tool-specific instruction adapter
Thin adapter to the shared AGENTS.md rules
Environment configuration
Reproducible project development environment
.github/workflows/ci.yml
Automated structural and project quality checks
.github/workflows/release.yml
Versioned release baseline
.github/workflows/cd.yml
Included deployment skeleton; configured during DEPLOY
These artifacts are operational project files, not a replacement for this method documentation. Their concrete format depends on the selected tools and development environment. A project README should provide a short description and link to this page rather than duplicating the complete method.
Fast Track for small changes
Fast Track reduces documentation and validation scope for small, localized changes within existing behavior and architecture. It does not introduce a seventh phase or a separate skill. A typo or a regression correction can qualify; new features, public contract changes, migrations, security changes, dependency changes and architecture decisions cannot. If the scope grows or eligibility is unclear, return to the regular flow.
Use an existing specification when behavior needs clarification. Otherwise, a short entry in docs/TASKS.md is sufficient. Record scope, the eligibility reason, an acceptance criterion, the validation plan, actual results and omitted checks with reasons. Shorten SPECIFY and record why DESIGN is skipped or shortened. Do not create a use-case document solely for Fast Track.
For behavior corrections, write a failing regression test before the fix and run relevant tests. Documentation-only changes need content and link checks, not artificial code tests. Required CI and human review still apply. Scoped validation does not certify the entire repository as release-ready or authorize release/deployment; a later release needs its normal validation.
Example: restore rejection of blank comments
Assume an existing specification already requires blank comments to be rejected, but a regression accepts whitespace-only input.
The acceptance criterion is: whitespace-only input is rejected and no comment is stored. A suitable test checks this at the affected boundary; adding unrelated tests at every layer is not required. Record real commands and results rather than copying a fictional “passed” result. For a spelling correction, use the same short record with content/link verification instead.
Architecture decisions and shared project knowledge
DESIGN creates an ADR only when a consequential choice needs a durable rationale, for example a persistence boundary, a technology choice or a cross-cutting constraint. Create docs/adr/ADR-NNN-short-title.md on demand with an unused number. No empty ADR directory or routine decision document is required.
Use five short sections: Status, Context, Alternatives, Decision and Consequences. The status starts as Proposed; record the authorized human's acceptance and review reference before treating it as Accepted. Preserve a replaced decision as Superseded and link its replacement.
docs/adr/ADR-NNN-short-title.md
Decision, alternatives, rationale, consequences and approval history
docs/PROJECT.md
Current architecture and links to relevant accepted decisions
AGENTS.md
Only durable, actionable constraints and ADR links
docs/TASKS.md
Active work, phase and links to decisions or validation evidence
Example: keep persistence behind application ports
An ADR might compare direct database access from controllers with access through an application port. If the team accepts the port-based boundary, PROJECT.md describes the resulting architecture. The corresponding short agent rule could be: “Do not access the database directly from API controllers; use the application port. See ADR-001.” This is an illustrative decision, not an ADR already created in the starter.
Agents can prepare the proposed ADR and associated documentation diffs together. The human review establishes acceptance; an agent proposal is not approval. When a decision changes, preserve its history and reconcile affected architecture descriptions and agent rules in the same reviewed change. Parallel branches must reconcile task state and decision identifiers before merge. This is a collaboration convention, not a lock or automatic synchronization service.
TDD and the Testing Pyramid
The testing pyramid balances fast feedback and realistic system confidence:
Unit tests ≈ 70%: domain rules and application logic;
Integration tests ≈ 20%: interfaces, adapters and infrastructure boundaries;
End-to-end tests ≈ 10%: complete user flows against the built artifact.
The proportions and the earlier 80% coverage target are teaching heuristics from the original overview, not empirically established AI-SDLC thresholds. The template does not enforce them. Coverage alone cannot establish assertion quality or acceptance-criterion completeness.
The proportions are guidelines, not a mathematical requirement. The important principle is to test each risk at the cheapest reliable boundary.
A typical CI expectation is:
unit and integration tests on pull requests;
static checks and formatting checks on pull requests;
end-to-end tests in a release or validation pipeline;
artifact build and publication only after required checks pass.
Clean Architecture Mapping
Clean Architecture makes dependencies explicit and keeps business rules independent from technical details.
The artifacts use the following shorthand for inward dependencies. It is not a required chain of imports: a persistence adapter can implement a repository interface in the application layer, while the domain remains independent of both:
domain ← application ← interfaces ← infrastructure
Domain
Entities, value objects and business rules
Unit tests
Application
Use cases, orchestration and repository interfaces
Unit tests
Interfaces
API, UI, CLI and other input/output boundaries
Integration tests
Infrastructure
Persistence, frameworks, external services and runtime wiring
Integration and containerized E2E tests
The domain and application layers should not depend on web frameworks, databases or vendor-specific infrastructure. Interfaces define boundaries and dependency injection points. Infrastructure implements the technical details behind those boundaries.
The exact directory names may vary by language and framework. The architecture decision belongs in docs/PROJECT.md; the method does not require an artificial restructure when an existing compatible structure is already clear.
Repository Layout and Tool Adapters
AI-SDLC keeps the method's working context close to the source code:
Projects may add tool adapters, environment configuration and automation workflows. These are implementation choices, not additional AI-SDLC phases or universal requirements. Keep skills/ as the canonical, agent-neutral source. If a selected agent needs another discovery path, use the project's adapter or setup script without changing the canonical artifacts.
Working with AI Agents
AI-SDLC treats the agent as a capable implementation partner operating within explicit constraints. The agent must not infer missing requirements from code alone.
Before changing code, the agent should:
identify the current phase and active use case;
inspect the relevant repository artifacts;
state assumptions when they affect scope or architecture;
preserve existing meaningful content;
keep changes small and traceable;
derive tests from acceptance criteria;
avoid unrelated refactoring and unnecessary file creation;
ask when requirements or architecture remain unclear.
The human remains responsible for:
approving the problem definition, scope and acceptance criteria;
deciding architectural boundaries and material trade-offs;
reviewing generated code, tests, dependencies and security implications;
approving releases and deployments.
Agents can work with GitHub Copilot or other compatible tools. The method is agent-neutral: the repository artifacts, lifecycle gates and human approvals matter more than the specific model or product.
Getting Started
AI-SDLC is tool-neutral. The method does not require GitHub, GitHub Copilot, Codespaces or a particular editor. It can be used with local or hosted repositories and with AI coding agents such as Codex, Claude Code, GitHub Copilot, Cline, Cursor, OpenCode, Kiro, Devin or comparable tools.
Choose or create a repository for the project.
Add or retain the AI-SDLC artifacts:
AGENTS.md,docs/PROJECT.md,docs/TASKS.md,docs/specs/and the phase skills.Adapt the project context, commands and agent integration to the selected tools.
Complete
docs/PROJECT.mdduring BOOTSTRAP.Define the first use case from
docs/specs/UC-TEMPLATE.md, or record a justified Fast Track task.Record the active phase, status and use case in
docs/TASKS.md.Execute one phase at a time, using
AGENTS.mdand the skill for the current phase.Review the outputs and evidence before selecting the next phase.
The AI-SDLC project template provides a convenient starting point with optional repository and tool setup. These are implementation conveniences, not requirements of the method. Follow the template documentation for the selected language, editor, agent and development environment.
Reading the example prompts
The examples use short, human-written prompts. A configured agent should load the repository instructions and discover the applicable skill automatically. Explicit instruction or skill paths are only needed as a fallback when discovery is unavailable. Execute only the selected phase and review its output before selecting the next.
A useful starting prompt is:
Reading the example prompts
The examples use short, human-written prompts. A configured agent should load the repository instructions and discover the applicable skill automatically. Explicit instruction or skill paths are only needed as a fallback when discovery is unavailable. Execute only the selected phase and review its output before selecting the next.
A useful starting prompt is:
Worked example: add comments to a record
This fictional example follows one change through all phases. It is an explanatory walkthrough, not a completed implementation or empirical study. Execute one prompt at a time and review its result. Replace assumptions with your actual project context.
1. Specify behavior
Example acceptance criterion: Given an existing record, when nonblank text and an author name are submitted, then the stored comment appears in its comment list with a timestamp. For blank text, validation fails and nothing is stored. Clarify ordering and permissions against the existing system.
CI, Releases and Deployment
Continuous integration
The baseline .github/workflows/ci.yml checks the existence of selected files and directories. It does not run application tests, linting or type checks. It runs git diff --check, but on a clean checkout there is normally no working-tree diff; this does not meaningfully validate whitespace in committed changes. During BOOTSTRAP and VALIDATE, extend it with the project's install, lint, type-check, unit and integration test commands.
Releases
The baseline .github/workflows/release.yml creates a GitHub Release with generated notes for v* tags after structural checks. A manual branch run skips publication. It does not build containers, run E2E tests, publish packages or require successful application CI. Those steps still need implementation to satisfy the intended VALIDATE outcome.
A project may extend the release workflow to:
build a package or container;
run end-to-end tests against the built artifact;
publish a package to an appropriate registry;
attach release notes and provenance information.
A release should correspond to a documented method or project state and should be traceable to the validated commit.
Continuous deployment
The template includes .github/workflows/cd.yml, triggered manually or by another workflow. Deployment is skipped unless CD_ENABLED is true; a successful preflight can therefore mean no deployment occurred. When enabled, it expects executable scripts/deploy.sh and scripts/smoke-test.sh; neither is supplied. These scripts must implement authentication, artifact selection and validation. The workflow does not enforce a successful release or pin the artifact. Do not assume the job-level activation condition works with environment-only variables; review activation and credential scope for the project. Configure it only after choosing a deployment platform and defining the required secrets. The workflow should deploy the validated artifact, perform a post-deploy smoke check and document how to recover from a failed deployment. Never store secret values in the repository.
SAFe and Kanban Alignment
AI-SDLC can be used with SAFe terminology without requiring a full SAFe implementation:
Epic or Feature
SPECIFY
System Architecture
DESIGN
Iteration execution
DEVELOP
System demo or validation
VALIDATE
Release and operate feedback
DEPLOY → feedback to SPECIFY
Kanban in GitHub Projects typically tracks:
Spec/Backlog → In progress → Review/CI → Done/Deployed
The board is a visibility and flow mechanism. The repository artifacts remain the source of truth for the active use case, architecture and lifecycle state.
Reference Implementation
BAIssue is the reference application, not the template. The classroom walkthrough starts from the template and builds a smaller issue-tracker slice for teaching.
A reference implementation should be a small, understandable application that demonstrates the method end to end. It should show:
a meaningful use-case specification;
explicit architecture boundaries;
tests derived from acceptance criteria;
CI and release evidence;
containerization or another reproducible build where appropriate;
a documented deployment workflow when deployment is in scope.
A reference implementation is for learning and comparison. It is not the student project template and should not be copied as a complete method documentation source.
Current implementation boundaries
The starter does not automate phase transitions, check acceptance-to-test traceability, enforce human review gates or automatically synchronize architecture decisions into agent instructions. Fast Track, ADRs and architecture feedback are now explicit repository instructions; their application and review remain human/agent responsibilities.
docs/TASKS.md holds one active context. Parallel branches can diverge and need reconciliation at merge time. The file is not a multi-agent coordination service. The root skills/ directory is intentionally agent-neutral. Run scripts/setup-skills.sh to expose it through supported agent paths; verify discovery in the actual tool. Explicit canonical paths remain a fallback.
Publication and Versioning
Current release — Version 1.0.0
Version 1.0.0 is the finalized AI-SDLC method and project template associated with the camera-ready paper submitted to the Upper-Rhine Artificial Intelligence Symposium (URAI) 2026. The AI-SDLC project template is maintained in alignment with this release.
Martin, A., & Schwander, S. (2026). The AI-SDLC Template and Method: AI-Assisted Software Development Life Cycle (Version 1.0.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.22833065
The immutable Version 1.0.0 research artifact is archived on Zenodo. This documentation describes the current AI-SDLC method and may evolve beyond Version 1.0.0.
Research publication
The AI-SDLC method and its empirical evaluation are described in:
Martin, A., & Schwander, S. (2026). A Lean and Spec-Driven AI-Assisted Software Development Lifecycle for Applied AI Education: The AI-SDLC Approach (arXiv:2609.24348). arXiv. https://doi.org/10.48550/arXiv.2609.24348
The camera-ready paper has been submitted for presentation at the Upper-Rhine Artificial Intelligence Symposium (URAI) 2026. The final publication in the URAI Journal will be linked here once available and will serve as the version of record.
Evaluation baseline — Version 1.0.0-beta
The empirical evaluation reported in the paper was conducted using the pre-release version of AI-SDLC. This version is preserved to ensure traceability between the empirical study and the evaluated artifact.
Martin, A., & Schwander, S. (2026). The AI-SDLC Template and Method Pre-Release (Version 1.0.0-beta) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.22724343
The subsequent Version 1.0.0 incorporates refinements informed by the evaluation and review process. The pre-release should therefore be used when reproducing or referring specifically to the evaluated artifact.
Version relationship
For scientific use, cite the immutable Zenodo release corresponding to the method version used and, where appropriate, the accompanying research paper.
Process changelog
September 2026 — refinement based on survey and review feedback
AI-SDLC was refined based on feedback from the student survey and the abstract review:
Fast Track: a shortened route for small corrections within the existing six-phase lifecycle.
Architecture decisions: on-demand ADRs in DESIGN record consequential choices and their rationale.
Collaboration: accepted architecture decisions feed back into current project documentation and relevant, human-reviewed rules in
AGENTS.md.Phase status:
PHASEidentifies the selected phase;STATUSdistinguishes readiness, work in progress, completion and blockers. Completing a phase retains its number, including BOOTSTRAP.Minimal agent instructions: shared rules are consolidated and phase-specific instructions shortened to reduce duplication.
Artifact snapshots: project template · reference implementation.
Before September 2026 — initial baseline
The six-phase AI-SDLC combined spec-driven development, TDD, architecture guidance and repository-local agent instructions. This version formed the basis of the student survey and the reviewed abstract.
Summary
The AI-SDLC working principle is:
The method keeps the workflow explicit, the implementation incremental, the evidence reviewable and the human accountable for consequential decisions.