ai-first-sdlc-practices

KO | EN

gitlite — search

#python #golang #machine-learning #rust #deep-learning #linux #docker #java #awesome #kubernetes #vue #pytorch #openai #open-source

ai-first-sdlc-practices

(★ 41)

Repo of the scripts I'm using to work with Claude and Gemini

ai-first-sdlc-practices Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**Table of Contents**

- [AI-First SDLC Practices](#ai-first-sdlc-practices)
  - [Prerequisites](#prerequisites)
  - [Setup](#setup)
    - [Plugin Install (Recommended)](#plugin-install-recommended)
    - [SDLC Method Selection](#sdlc-method-selection)
    - [Available Plugins](#available-plugins)
    - [Available Skills](#available-skills)
    - [Agent-Based Setup (Pre-release / Development)](#agent-based-setup-pre-release--development)
    - [Script-Based Setup (Legacy)](#script-based-setup-legacy)
  - [How It Works](#how-it-works)
    - [Rules](#rules)
    - [Validation](#validation)
    - [Agents](#agents)
  - [Documentation](#documentation)
    - [Agent Development](#agent-development)
  - [Integration Testing](#integration-testing)
  - [Known Limitations](#known-limitations)
  - [Zero Technical Debt Policy](#zero-technical-debt-policy)
  - [Development](#development)
    - [Using the Framework (Your Project)](#using-the-framework-your-project)
    - [Developing the Framework (This Repo)](#developing-the-framework-this-repo)
    - [Current Version: 1.8.0](#current-version-180)
  - [Contributing](#contributing)
  - [License](#license)

# AI-First SDLC Practices

A framework for integrating AI agents as primary developers while maintaining quality and process compliance. Ships 56 specialist agents across 12 plugins covering AI/ML, full-stack, cloud, security, project management, documentation, and containerised delegation. Automates the specify-architect-implement-review workflow with skills that enforce zero technical debt from day one.

## Prerequisites

- [Claude Code](https://claude.ai/claude-code) CLI (the host application for all plugins)
- Python 3.10+ (validation tools and scripts)
- Git
- Optional: [GitHub CLI](https://cli.github.com/) (`gh`) for PR-related features
- Optional: Docker (for `sdlc-workflows` containerised delegation)

## Setup

### Plugin Install (Recommended)

Install the plugin family from the Claude Code marketplace. This is the standard approach for using the framework in your projects.

**Step 1: Add the marketplace and install the core plugin**
```
/plugin marketplace add SteveGJones/ai-first-sdlc-practices
/plugin install sdlc-core@ai-first-sdlc
```

**Step 2: Configure your team**
```
/sdlc-core:setup-team
```

This presents project types (Full-stack, AI/ML, Cloud, API, Security, Custom) and installs the matching team plugins. For example, a full-stack web app installs:

| Plugin | Description |
|--------|-------------|
| `sdlc-core` | Rules, validators, enforcement, workflows (always installed) |
| `sdlc-team-common` | Solution architect, research agent, performance engineer, database architect |
| `sdlc-team-fullstack` | Web full-stack — frontend, backend, API, data, DevOps, UX, integration architects |
| `sdlc-team-mobile` + `sdlc-team-ios` / `sdlc-team-android` | Mobile — shared base (architecture, interaction UX) + platform design (Apple HIG / Material Design 3) |

**Step 3: Start working**
```
/sdlc-core:new-feature 1 my-feature "Description of the feature"
```

### SDLC Method Selection

The framework supports **four SDLC delivery structures**. The `setup-team` skill asks which one applies to your project; you can also pick later via `/sdlc-core:commission`. Most projects pick **single-team** (the default).

| Method | When to use | Team size | What you install |
|--------|-------------|-----------|-------------------|
| **Single-team** (default) | Organic delivery, no formal phase gates. Most projects pick this. | 3–10 | `sdlc-core` + team plugins (no extra bundle) |
| **Solo** | Fast-iteration, lightweight constitution overlay. | 1–2 | `sdlc-core` + team plugins; commission with `--option solo` |
| **Programme** (Method 1) | Multi-team programme work with formal phase gates (requirements → design → test → code) and mandatory cross-phase review. | 11–50 across 2–5 teams | `sdlc-programme` bundle + commission |
| **Assured** (Method 2) | Regulated industries (DO-178C, IEC 62304, ISO 26262, FDA 21 CFR Part 820). Bidirectional traceability, positional namespace IDs, DDD decomposition, typed evidence statuses, standard-specific exports. | Any | `sdlc-assured` bundle (v0.2.0 audit-ready at the tooling layer) + commission |

**Decision tree, comparison table, trade-offs, and migration notes:** see [docs/METHODS-GUIDE.md](docs/METHODS-GUIDE.md).

### Available Plugins

| Plugin | Agents | Skills | Description |
|--------|--------|--------|-------------|
| [`sdlc-core`](plugins/sdlc-core/README.md) | 4 | 9 | Rules, validators, enforcement, workflows, four-option commissioning (solo / single-team / programme / assured) — always install |
| [`sdlc-team-common`](plugins/sdlc-team-common/README.md) | 8 | — | Cross-cutting architects, researchers, performance engineers |
| [`sdlc-team-ai`](plugins/sdlc-team-ai/README.md) | 14 | — | AI/ML specialists — architects, prompt engineers, RAG designers |
| [`sdlc-team-fullstack`](plugins/sdlc-team-fullstack/README.md) | 9 | — | Web full-stack — frontend, backend, API, data, DevOps, UX & integration architects |
| [`sdlc-team-mobile`](plugins/sdlc-team-mobile/README.md) | 2 | — | Shared mobile base — cross-platform architecture + interaction UX (pairs with iOS/Android) |
| [`sdlc-team-ios`](plugins/sdlc-team-ios/README.md) | 4 | 4 | iOS/iPadOS — HIG, SwiftUI, release & performance agents + TestFlight/App Store skills |
| [`sdlc-team-android`](plugins/sdlc-team-android/README.md) | 6 | 4 | Android — MD3, Compose, app architecture, Gradle, Play release & performance agents + scaffold/signing/release skills |
| [`sdlc-team-cloud`](plugins/sdlc-team-cloud/README.md) | 3 | — | Cloud, container, SRE specialists |
| [`sdlc-team-security`](plugins/sdlc-team-security/README.md) | 5 | — | Security, compliance, privacy specialists |
| [`sdlc-team-pm`](plugins/sdlc-team-pm/README.md) | 5 | — | Agile coach, delivery manager, progress tracking |
| [`sdlc-team-docs`](plugins/sdlc-team-docs/README.md) | 2 | — | Technical writer, documentation architect |
| [`sdlc-lang-python`](plugins/sdlc-lang-python/README.md) | 1 | — | Python-specific validation, patterns, expert agent |
| [`sdlc-lang-javascript`](plugins/sdlc-lang-javascript/README.md) | 1 | — | JavaScript/TypeScript validation and patterns |
| [`sdlc-lang-swift`](plugins/sdlc-lang-swift/README.md) | 1 | — | Swift language expert — idiomatic Swift 6.2, concurrency, generics, macros, SwiftPM |
| [`sdlc-lang-kotlin`](plugins/sdlc-lang-kotlin/README.md) | 1 | — | Kotlin language expert — idiomatic Kotlin 2.x, coroutines & Flow, sealed/data/value classes, KMP |
| [`sdlc-knowledge-base`](plugins/sdlc-knowledge-base/README.md) | 2 | 8 | Filesystem-based knowledge base — librarian agent, hash-tracked indexes, ingest/query/lint |
| [`sdlc-workflows`](plugins/sdlc-workflows/README.md) | 1 | 6 | Containerised delegation — Archon-orchestrated DAG workflows in isolated Docker containers |
| [`sdlc-programme`](plugins/sdlc-programme/README.md) | 0 | 5 | **Method 1 substrate** — formal phase gates (requirements → design → test → code) with mandatory cross-phase review. Skill+validator bundle for multi-team programme work. |
| [`sdlc-assured`](plugins/sdlc-assured/README.md) | 0 | 8 | **Method 2 substrate (v0.2.0 audit-ready)** — positional namespace IDs, bidirectional traceability, DDD decomposition, KB-for-code, standard-specific exports (DO-178C / IEC 62304 / ISO 26262 / FDA DHF). Skill+validator bundle for regulated industries. |

### Available Skills

**sdlc-core** (always installed):

| Skill | Description |
|-------|-------------|
| `/sdlc-core:validate` | Run validation pipeline (`--syntax`, `--quick`, `--pre-push`) |
| `/sdlc-core:new-feature` | Create feature proposal, retrospective, and branch |
| `/sdlc-core:commit` | Validated commit with test execution |
| `/sdlc-core:pr` | Full validation + PR creation |
| `/sdlc-core:setup-team` | Configure team formation for your project; asks the four-option SDLC method question |
| `/sdlc-core:commission` | Commission a project to one of the four SDLC options (solo / single-team / programme / assured); records choice in `.sdlc/team-config.json` |
| `/sdlc-core:setup-ci` | Generate GitHub Actions workflow |
| `/sdlc-core:release-plugin` | Package source into plugins |
| `/sdlc-core:rules` | AI-First SDLC compliance rules and standards |

**sdlc-knowledge-base** (install for evidence-grounded projects):

| Skill | Description |
|-------|-------------|
| `/sdlc-knowledge-base:kb-init` | Initialise knowledge base with optional starter pack |
| `/sdlc-knowledge-base:kb-ingest` | Integrate a new source into the library |
| `/sdlc-knowledge-base:kb-query` | Query the library with structured evidence retrieval |
| `/sdlc-knowledge-base:kb-lint` | Six-check health report on library quality |
| `/sdlc-knowledge-base:kb-rebuild-indexes` | Hash-based incremental rebuild of shelf-index |
| `/sdlc-knowledge-base:kb-validate-citations` | Spot citation hallucinations (DOI/arXiv validation) |
| `/sdlc-knowledge-base:kb-promote-answer-to-library` | File a query result as a new library page |
| `/sdlc-knowledge-base:kb-staleness-check` | Check for shelf-index drift (wire into pre-push hooks) |

**sdlc-workflows** (install for containerised delegation):

| Skill | Description |
|-------|-------------|
| `/sdlc-workflows:workflows-setup` | First-time setup: install Archon, build images, scaffold dirs |
| `/sdlc-workflows:workflows-run` | Execute a workflow by name |
| `/sdlc-workflows:workflows-status` | Show running/recent workflow runs |
| `/sdlc-workflows:author-workflow` | Recommend or author a workflow for a task |
| `/sdlc-workflows:deploy-team` | Build a team image from a manifest |
| `/sdlc-workflows:manage-teams` | Team lifecycle coaching and fleet reporting |

### Agent-Based Setup (Pre-release / Development)

For testing unreleased agents or contributing to the framework, install agents directly from the repository. This approach gives you access to agents before they're published as plugins.

```bash
# Download the setup orchestrator
curl -s https://raw.githubusercontent.com/SteveGJones/ai-first-sdlc-practices/main/agents/v3-setup-orchestrator.md > v3-setup-orchestrator.md
mkdir -p .claude/agents && mv v3-setup-orchestrator.md .claude/agents/

# Restart Claude Code, then:
# "Use the v3-setup-orchestrator agent to set up AI-First SDLC for my project"
```

The orchestrator interviews you about your project and downloads only the agents you need. Use this approach when:
- You want agents that haven't been released as plugins yet
- You're contributing to the framework and testing changes
- You need a custom agent selection not covered by the plugin team presets

### Script-Based Setup (Legacy)

The original Python script approach. Still functional but superseded by the plugin system.

```bash
curl -sSL https://raw.githubusercontent.com/SteveGJones/ai-first-sdlc-practices/main/setup-smart.py > setup-smart.py
python setup-smart.py "describe your project" --non-interactive
```

## How It Works

The framework enforces a specify-architect-implement-review workflow:

1. **Feature proposal** (`docs/feature-proposals/XX-name.md`) documents what and why
2. **Architecture** designed with specialist agents before coding
3. **Implementation** with continuous testing and validation
4. **Review** by code-review-specialist and verification-enforcer agents
5. **Ship** with full validation passing

### Rules

All rules are in [CONSTITUTION.md](CONSTITUTION.md) — 11 articles covering git workflow, documentation, architecture, code quality, validation, agent collaboration, logging, security, self-review, verification, and progressive levels (Prototype/Production/Enterprise).

### Validation

```bash
/sdlc-core:validate --syntax      # After writing code
/sdlc-core:validate --quick       # Before commits
/sdlc-core:validate --pre-push    # Before PRs
```

The validation pipeline runs up to 10 checks: syntax, lint, format, technical debt, tests, import check, type safety, security, and smoke test. Each check includes a preflight gate that reports missing tools with install instructions.

### Agents

The framework provides 56 specialist agents across 12 plugins. Each plugin's README lists its agents in detail.

**sdlc-core** (4 agents — always installed):

| Agent | Role |
|-------|------|
| `sdlc-enforcer` | Process compliance and quality gates |
| `critical-goal-reviewer` | Requirements verification and gap analysis |
| `code-review-specialist` | Code quality, security (OWASP), patterns |
| `verification-enforcer` | Docs-code fidelity, test coverage, runtime proof |

**Team plugins** (64 agents across 15 plugins):

| Plugin | Agents | Highlights |
|--------|--------|------------|
| `sdlc-team-ai` | 14 | Prompt engineer, RAG designer, MCP architect, orchestration architect, context engineer |
| `sdlc-team-fullstack` | 9 | Frontend/backend/API architects, DevOps, UX-UI, data architect, integration orchestrator |
| `sdlc-team-mobile` | 2 | Mobile architect, mobile-UX architect (shared cross-platform base) |
| `sdlc-team-ios` | 4 | Apple HIG architect, SwiftUI architect, iOS release engineer, iOS performance specialist |
| `sdlc-team-android` | 6 | Material Design 3, Jetpack Compose, app architecture, Gradle, Play release, performance |
| `sdlc-team-common` | 8 | Solution architect, database architect, performance engineer, deep-research agent |
| `sdlc-team-security` | 5 | Security architect, compliance auditor, data privacy officer |
| `sdlc-team-pm` | 5 | Agile coach, delivery manager, retrospective miner |
| `sdlc-team-cloud` | 3 | Cloud architect, container specialist, SRE specialist |
| `sdlc-team-docs` | 2 | Technical writer, documentation architect |
| `sdlc-knowledge-base` | 2 | Research librarian, knowledge updater |
| `sdlc-lang-python` | 1 | Python language expert |
| `sdlc-lang-javascript` | 1 | JavaScript/TypeScript language expert |
| `sdlc-lang-swift` | 1 | Swift language expert (pairs with sdlc-team-ios) |
| `sdlc-lang-kotlin` | 1 | Kotlin language expert (pairs with sdlc-team-android) |
| `sdlc-workflows` | 1 | Delegation coordinator |

See [AGENT-INDEX.md](AGENT-INDEX.md) for the full catalog with detailed descriptions.

## Documentation

| Document | Description |
|----------|-------------|
| [CONSTITUTION.md](CONSTITUTION.md) | All rules — single source of truth (11 articles) |
| [CLAUDE-CORE.md](CLAUDE-CORE.md) | Operational instructions, commands, context loading |
| [CLAUDE.md](CLAUDE.md) | Gateway file — concise entry point for Claude Code |
| [docs/HOWTO.md](docs/HOWTO.md) | Comprehensive usage guide |
| [docs/QUICK-REFERENCE.md](docs/QUICK-REFERENCE.md) | Command cheat sheet |
| [docs/METHODS-GUIDE.md](docs/METHODS-GUIDE.md) | Decision tree for the four SDLC methods (solo / single-team / programme / assured) — when to use each, comparison table, trade-offs, migration notes |
| [docs/PLUGIN-CONSUMER-GUIDE.md](docs/PLUGIN-CONSUMER-GUIDE.md) | How the plugin ecosystem works for end users |
| [CHANGELOG.md](CHANGELOG.md) | Version history and release notes |
| [CLAUDE-CONTEXT-workflows.md](CLAUDE-CONTEXT-workflows.md) | Containerised delegation reference (team manifests, workflows, Docker) |

### Agent Development

| Document | Description |
|----------|-------------|
| [Agent Creation Guide](docs/AGENT-CREATION-GUIDE.md) | How to write effective agents |
| [Agent Format Spec](docs/AGENT-FORMAT-SPEC.md) | Technical specification |
| [AGENT-INDEX.md](AGENT-INDEX.md) | Full catalog of all agents |

## Integration Testing

The framework includes an automated integration test at `tests/integration/`. It uses Ralph to drive Claude through 10 phases — from blank repo to running app — producing a Build Journal Web App that documents its own construction. The build journal serves as both a demo and a framework quality report.

See [tests/integration/README.md](tests/integration/README.md) for how to run it.

## Known Limitations

1. **`.claude/` write protection**: Claude Code blocks writes to `.claude/` in project directories (security feature). Project-scoped plugin installation and project-scoped memory both require workarounds. See [#81](https://github.com/SteveGJones/ai-first-sdlc-practices/issues/81).

2. **Slash commands in automated loops**: Skills like `/sdlc-core:new-feature` and `/sdlc-core:validate` require an interactive Claude Code session. They cannot be invoked from Ralph loops or CI scripts. The loop can read the skill's SKILL.md and execute the steps manually.

3. **Plugin cache**: Claude Code caches plugins globally at `~/.claude/plugins/cache/`. When testing new plugin versions, clear the cache first: `rm -rf ~/.claude/plugins/cache/ai-first-sdlc/`

## Zero Technical Debt Policy

The framework enforces architecture-first development:

1. No code without architecture — design documents required before implementation
2. No TODOs, FIXMEs, commented code, or `any` types
3. Type safety mandatory — strict typing in all languages
4. Tests mandatory — written alongside implementation, not after
5. Smoke test mandatory — the app must start and respond before committing
6. Automated enforcement via pre-commit hooks and CI/CD validation

See [CONSTITUTION.md](CONSTITUTION.md) Articles 4, 5, and 10 for the complete rules.

## Development

### Using the Framework (Your Project)

Install the plugins, run setup-team, and follow the workflow. The framework tools validate your code, the agents assist your design, and the skills enforce the process.

### Developing the Framework (This Repo)

This repo dogfoods its own practices. Key development conventions:

- Branch naming: `feature/`, `fix/`, `docs/`
- Feature proposals required before implementation
- Retrospective required before PR
- Plugin source lives in `skills/`, `agents/`, `tools/` — packaged to `plugins/` via `release-mapping.yaml`
- Run `/sdlc-core:release-plugin` to package source into plugins

### Current Version: [1.8.0](CHANGELOG.md)

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT License — see [LICENSE](LICENSE) for details.

ai-first-sdlc-practices

ai-first-sdlc-practices Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

ai-first-sdlc-practices

ai-first-sdlc-practices Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README