|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +## Project overview |
| 4 | + |
| 5 | +AI-DLC (AI-Driven Development Life Cycle) is a methodology for guiding AI coding |
| 6 | +agents through structured software development workflows. This repository contains |
| 7 | +the core workflow rules, detailed phase-specific rules, and an evaluator framework. |
| 8 | + |
| 9 | +The distributable product is the `aidlc-rules/` directory, which is zipped and |
| 10 | +published via GitHub Releases. |
| 11 | + |
| 12 | +## Repository structure |
| 13 | + |
| 14 | +```text |
| 15 | +aidlc-rules/ |
| 16 | +├── aws-aidlc-rules/ # Core workflow entry point (DO NOT rename) |
| 17 | +│ └── core-workflow.md |
| 18 | +└── aws-aidlc-rule-details/ # Detailed rules referenced by the workflow (DO NOT rename) |
| 19 | + ├── common/ # Shared guidance across all phases |
| 20 | + ├── inception/ # Planning and architecture rules |
| 21 | + ├── construction/ # Design and implementation rules |
| 22 | + ├── extensions/ # Optional cross-cutting constraint rules |
| 23 | + └── operations/ # Deployment and monitoring rules |
| 24 | +scripts/aidlc-evaluator/ # Python evaluation framework (uv-managed) |
| 25 | +docs/ |
| 26 | +├── ADMINISTRATIVE_GUIDE.md # CI/CD, workflows, secrets, release process |
| 27 | +├── DEVELOPERS_GUIDE.md # Local builds (CodeBuild, act), security scanners |
| 28 | +├── WORKING-WITH-AIDLC.md # User guide for the AI-DLC methodology |
| 29 | +├── GENERATED_DOCS_REFERENCE.md # Full aidlc-docs/ directory reference |
| 30 | +└── writing-inputs/ # Guides and examples for vision/tech-env documents |
| 31 | +.github/ |
| 32 | +├── workflows/ # CI/CD pipelines (8 workflows) |
| 33 | +├── dependabot.yml # Dependabot dependency update configuration |
| 34 | +├── CODEOWNERS # Code ownership rules for PR reviews |
| 35 | +├── ISSUE_TEMPLATE/ # Issue templates |
| 36 | +├── pull_request_template.md # PR template with contributor statement |
| 37 | +└── labeler.yml # Auto-label rules (path → label mapping) |
| 38 | +.claude/ # Claude Code project settings |
| 39 | +``` |
| 40 | + |
| 41 | +## Key documentation |
| 42 | + |
| 43 | +- [CONTRIBUTING.md](CONTRIBUTING.md) — contribution process and conventions |
| 44 | +- [docs/ADMINISTRATIVE_GUIDE.md](docs/ADMINISTRATIVE_GUIDE.md) — CI/CD architecture, |
| 45 | + protected environments, secrets, permissions, and release process |
| 46 | +- [docs/DEVELOPERS_GUIDE.md](docs/DEVELOPERS_GUIDE.md) — running CodeBuild locally, |
| 47 | + security scanner details and remediation instructions |
| 48 | +- [docs/WORKING-WITH-AIDLC.md](docs/WORKING-WITH-AIDLC.md) — user guide for the |
| 49 | + AI-DLC methodology (context management, prompt patterns, phase walkthroughs) |
| 50 | +- [docs/GENERATED_DOCS_REFERENCE.md](docs/GENERATED_DOCS_REFERENCE.md) — complete |
| 51 | + reference for the `aidlc-docs/` directory structure generated during workflows |
| 52 | +- [docs/writing-inputs/](docs/writing-inputs/) — guides and examples for vision and |
| 53 | + technical environment documents |
| 54 | + |
| 55 | +**Which docs to read by task type:** |
| 56 | + |
| 57 | +- CI/CD, workflows, or releases → `ADMINISTRATIVE_GUIDE.md`, `DEVELOPERS_GUIDE.md` |
| 58 | +- aidlc-rules content → `WORKING-WITH-AIDLC.md`, `GENERATED_DOCS_REFERENCE.md` |
| 59 | +- Vision or technical environment documents → `docs/writing-inputs/` |
| 60 | + |
| 61 | +## Setup commands |
| 62 | + |
| 63 | +```bash |
| 64 | +# Lint all markdown files |
| 65 | +npx markdownlint-cli2 "**/*.md" |
| 66 | + |
| 67 | +# Fix markdown lint issues automatically |
| 68 | +npx markdownlint-cli2 --fix "**/*.md" |
| 69 | + |
| 70 | +# Run evaluator tests (from scripts/aidlc-evaluator/) |
| 71 | +cd scripts/aidlc-evaluator && uv run pytest |
| 72 | +``` |
| 73 | + |
| 74 | +## Code style |
| 75 | + |
| 76 | +- All content is Markdown — follow the `.markdownlint-cli2.yaml` configuration |
| 77 | +- MD013 (line length) is disabled — long URLs, tables, and code examples are acceptable |
| 78 | +- MD033 (inline HTML) is disabled — `<img>` tags are used for screenshots |
| 79 | +- MD024 (duplicate headings) is disabled — section names repeat across platform guides |
| 80 | +- MD036 (emphasis as heading) is disabled — bold text used as sub-labels in lists |
| 81 | +- MD060 (table alignment) is enforced — table pipes must be vertically aligned |
| 82 | +- MD040 (fenced code language) is enforced — always specify a language on code fences |
| 83 | +- Commit messages follow [conventional commits](https://www.conventionalcommits.org/) |
| 84 | + (e.g., `feat:`, `fix:`, `docs:`, `chore:`) |
| 85 | + |
| 86 | +## Testing instructions |
| 87 | + |
| 88 | +- Test rule changes with at least one supported platform (Amazon Q Developer, Kiro, |
| 89 | + Cursor, Cline, Claude Code, or GitHub Copilot) before submitting |
| 90 | +- If adding or updating installation instructions, test on macOS, Windows CMD, and |
| 91 | + Windows PowerShell |
| 92 | +- Run `npx markdownlint-cli2 "**/*.md"` before committing to catch lint issues |
| 93 | +- The pre-commit hook runs markdownlint automatically if configured |
| 94 | + |
| 95 | +## PR instructions |
| 96 | + |
| 97 | +- PR titles must follow conventional commits format (e.g., `fix: description`) |
| 98 | +- Always include this contributor statement at the end of the PR body: |
| 99 | + |
| 100 | + > By submitting this pull request, I confirm that you can use, modify, copy, |
| 101 | + > and redistribute this contribution, under the terms of the |
| 102 | + > [project license](https://github.com/awslabs/aidlc-workflows/blob/main/LICENSE). |
| 103 | +
|
| 104 | +- CI enforces: conventional commit title, contributor statement, markdownlint, and |
| 105 | + a do-not-merge label check |
| 106 | +- Use the structure from `.github/pull_request_template.md` |
| 107 | + |
| 108 | +## Security scanners |
| 109 | + |
| 110 | +Six scanners run on every push to `main`, every PR, and daily. All HIGH and CRITICAL |
| 111 | +findings must be remediated or have documented risk acceptance before merge. |
| 112 | + |
| 113 | +| Scanner | Detects | Fails on | Config | |
| 114 | +| -------- | ---------------------- | --------------------------- | ------------------------------------------- | |
| 115 | +| Bandit | Python SAST issues | High confidence findings | `.bandit` | |
| 116 | +| Semgrep | Multi-language SAST | Any finding (PRs: new only) | `.semgrepignore` | |
| 117 | +| Grype | Dependency CVEs | High/critical CVEs | `.grype.yaml` | |
| 118 | +| Gitleaks | Secrets in git history | Any non-baselined secret | `.gitleaks.toml`, `.gitleaks-baseline.json` | |
| 119 | +| Checkov | IaC misconfigurations | Any check failure | `.checkov.yaml` | |
| 120 | +| ClamAV | Malware | Any detection | None | |
| 121 | + |
| 122 | +Inline suppression patterns: |
| 123 | + |
| 124 | +- Bandit: `# nosec BXXX — justification` |
| 125 | +- Semgrep: `# nosemgrep: rule-id — justification` |
| 126 | +- Checkov: `# checkov:skip=CKV_ID:justification` |
| 127 | + |
| 128 | +For full remediation and suppression details, see |
| 129 | +[docs/DEVELOPERS_GUIDE.md](docs/DEVELOPERS_GUIDE.md#security-scanners). |
| 130 | + |
| 131 | +## Important constraints |
| 132 | + |
| 133 | +- The folder names `aws-aidlc-rules/` and `aws-aidlc-rule-details/` are part of the |
| 134 | + public contract — do not rename, move, or reorganize them |
| 135 | +- Do not duplicate content across rules — place shared guidance in `common/` and |
| 136 | + reference it |
| 137 | +- Keep the core methodology IDE/agent/model agnostic |
| 138 | +- Security issues must be reported via |
| 139 | + [AWS vulnerability reporting](http://aws.amazon.com/security/vulnerability-reporting/), |
| 140 | + not public GitHub issues |
| 141 | +- `CHANGELOG.md` is auto-generated by git-cliff — do not edit manually |
| 142 | + |
| 143 | +## Agent-run snippets (added by Copilot) |
| 144 | + |
| 145 | +Short guidance for agents: prefer the repository uv wrapper and npx-based tools. Read docs/DEVELOPERS_GUIDE.md and docs/ADMINISTRATIVE_GUIDE.md before running any commands. |
| 146 | + |
| 147 | +Tests (uv): |
| 148 | + |
| 149 | +```bash |
| 150 | +uv run pytest |
| 151 | +uv run pytest --cov --cov-report=term-missing |
| 152 | +``` |
| 153 | + |
| 154 | +Markdown lint (npx): |
| 155 | + |
| 156 | +```bash |
| 157 | +npx markdownlint-cli2 "**/*.md" |
| 158 | +npx markdownlint-cli2 --fix "**/*.md" |
| 159 | +``` |
| 160 | + |
| 161 | +Dockerized security scans (recommended for local, cross-platform): |
| 162 | + |
| 163 | +```bash |
| 164 | +# Grype |
| 165 | +docker run --rm -v "$PWD:/workspace" anchore/grype:latest grype dir:/workspace -o sarif=grype.sarif |
| 166 | +# Gitleaks |
| 167 | +docker run --rm -v "$PWD:/repo" zricethezav/gitleaks:latest detect --source /repo --report-format sarif --report-path gitleaks.sarif |
| 168 | +# Semgrep |
| 169 | +docker run --rm -v "$PWD:/src" returntocorp/semgrep semgrep --config=r/all --sarif /src > semgrep.sarif |
| 170 | +# Checkov |
| 171 | +docker run --rm -v "$PWD:/src" bridgecrew/checkov --directory /src --output-file-path checkov.sarif --output sarif |
| 172 | +# Bandit |
| 173 | +docker run --rm -v "$PWD:/src" python:3.12-slim bash -c "pip install -q bandit && bandit -r /src -f sarif -o /src/bandit.sarif" |
| 174 | +# ClamAV |
| 175 | +docker run --rm -v "$PWD:/data" mkodockx/docker-clamav clamscan -r /data --log=/data/clamdscan.txt |
| 176 | +``` |
| 177 | + |
| 178 | +Notes: |
| 179 | + |
| 180 | +- These commands write SARIF/text artifacts to the project root so CI/agents can consume them. |
| 181 | +- CI already runs scanners; use these for local verification when Docker is available. |
| 182 | +- If Docker is unavailable, use the platform-specific installs documented in docs/DEVELOPERS_GUIDE.md. |
0 commit comments