Skip to content

Commit 0d9de40

Browse files
tbitcsoz-agent
tbitcs
and
oz-agent
committed
feat: #179 Codity.ai integration — CodityAdapter, codity-ai-review skill, ARCH §39, REQ-354/355/356/357, TEST-354/355/356/357
- src/specsmith/integrations/codity.py: CodityAdapter generates CI workflow for GitHub (default), GitLab, Azure DevOps; writes docs/codity-setup.md; appends LEDGER.md TODO checklist; VCS detected from scaffold.yml + heuristics - src/specsmith/integrations/__init__.py: register CodityAdapter as 'codity' - src/specsmith/skills/governance.py: codity-ai-review governance skill (70th skill) - src/specsmith/templates/agents.md.j2: Codity pre-commit rule section - docs/ARCHITECTURE.md §39: CodityAdapter architecture + I15 invariant - docs/requirements/overflow.yml: REQ-354/355/356 (Codity integration) - docs/tests/overflow.yml: TEST-354/355/356/357 (adapter, VCS detection, skill, template) - docs/site/skills-index.md: Governance (10→11), 69→70 built-in skills - docs/site/commands.md: specsmith integrate section with codity adapter docs - README.md: Codity.ai AI Code Review Integration section; overflow.yml range 353→356 - tests/test_integrations_codity.py: 40 tests, all green (831 total, 28/28 audit) Co-Authored-By: Oz <oz-agent@warp.dev>
1 parent d855024 commit 0d9de40

15 files changed

Lines changed: 1017 additions & 4 deletions

File tree

‎.specsmith/requirements.json‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3111,5 +3111,36 @@
31113111
"test_ids": [
31123112
"TEST-353"
31133113
]
3114+
},
3115+
{
3116+
"id": "REQ-354",
3117+
"title": "CodityAdapter Scaffolds AI Code Review CI Workflow",
3118+
"description": "specsmith MUST provide a CodityAdapter registered as 'codity' in the integrations registry. CodityAdapter.generate() MUST detect the VCS host from scaffold.yml content ('gitlab' keyword → gitlab, 'azure' keyword → azure, else github) and from directory heuristics (.gitlab-ci.yml → gitlab, azure-pipelines.yml → azure). For github it MUST write .github/workflows/codity-review.yml; for gitlab it MUST write .gitlab-ci-codity.yml; for azure it MUST write .azure-pipelines/codity-review.yml. All variants MUST install the Codity CLI via the official install script, run 'codity review --staged', and require CODITY_ACCESS_TOKEN. GitLab and Azure variants MUST additionally call 'codity config set-pat --provider <vcs>'. generate() MUST also write docs/codity-setup.md (one-time setup checklist) and append a TODO checklist to LEDGER.md if it exists. The adapter MUST be discoverable via specsmith integrate codity.",
3119+
"source": "ARCHITECTURE.md §39",
3120+
"status": "implemented",
3121+
"test_ids": [
3122+
"TEST-354",
3123+
"TEST-355"
3124+
]
3125+
},
3126+
{
3127+
"id": "REQ-355",
3128+
"title": "AGENTS.md Template Includes Codity.ai Pre-commit Rule",
3129+
"description": "The AGENTS.md Jinja2 template (agents.md.j2) MUST include a 'Codity.ai Code Review' section that instructs agents: if 'codity doctor' exits 0 (Codity is configured), run 'codity review --staged' before any commit touching production code; HIGH-severity findings are blocking; MEDIUM-severity findings require inline acknowledgement in the commit message; setup is via 'specsmith integrate codity --project-dir .'.",
3130+
"source": "ARCHITECTURE.md §39",
3131+
"status": "implemented",
3132+
"test_ids": [
3133+
"TEST-357"
3134+
]
3135+
},
3136+
{
3137+
"id": "REQ-356",
3138+
"title": "codity-ai-review Governance Skill in Skills Catalog",
3139+
"description": "specsmith MUST include a 'codity-ai-review' SkillEntry in the governance domain skills catalog. The skill MUST document: Codity CLI install command (curl install script), codity login (magic-link browser auth), codity init (per-repo initialisation), daily commands (review --staged, scan --staged, test-gen --staged, doctor), the AGENTS.md blocking rule (HIGH severity = commit blocked, MEDIUM = acknowledgement required), CI integration via specsmith integrate codity, GitHub App setup, GitLab PAT setup (codity config set-pat --provider gitlab), and Azure DevOps PAT setup. The skill MUST be tagged with codity, ai-review, code-review, security, test-gen, ci, github, gitlab, azure, staged, pre-commit and discoverable via specsmith skill list.",
3140+
"source": "ARCHITECTURE.md §39",
3141+
"status": "implemented",
3142+
"test_ids": [
3143+
"TEST-356"
3144+
]
31143145
}
31153146
]

‎.specsmith/testcases.json‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3452,5 +3452,49 @@
34523452
"input": "list_tools_for_type for each new type; check _TYPE_LABELS",
34533453
"expected_behavior": "Each type has correct build tool; all five types in _TYPE_LABELS",
34543454
"confidence": 0.95
3455+
},
3456+
{
3457+
"id": "TEST-354",
3458+
"title": "CodityAdapter Generates GitHub Workflow by Default",
3459+
"description": "CodityAdapter().generate(config, tmp_path) on a directory with no VCS signals MUST create .github/workflows/codity-review.yml containing 'codity review --staged', 'curl -fsSL https://cli.codity.ai/install.sh | sh', 'CODITY_ACCESS_TOKEN', and 'actions/checkout@v4'. It MUST also create docs/codity-setup.md. When LEDGER.md exists, a TODO checklist entry MUST be appended containing 'codity login' and 'codity doctor'. CodityAdapter().name MUST equal 'codity'.",
3460+
"requirement_id": "REQ-354",
3461+
"type": "unit",
3462+
"verification_method": "pytest",
3463+
"input": "CodityAdapter().generate(mock_config, tmp_path); tmp_path has no scaffold.yml or VCS hint files",
3464+
"expected_behavior": ".github/workflows/codity-review.yml created; docs/codity-setup.md created; LEDGER.md appended; name == 'codity'",
3465+
"confidence": 0.95
3466+
},
3467+
{
3468+
"id": "TEST-355",
3469+
"title": "CodityAdapter Detects GitLab and Azure VCS from Scaffold or Directory",
3470+
"description": "When scaffold.yml contains 'gitlab' (case-insensitive), _detect_vcs() MUST return 'gitlab' and generate() MUST write .gitlab-ci-codity.yml (not a GitHub workflow). When scaffold.yml contains 'azure', _detect_vcs() MUST return 'azure' and generate() MUST write .azure-pipelines/codity-review.yml. When .gitlab-ci.yml exists in the project root (no scaffold.yml), _detect_vcs() MUST return 'gitlab'. When azure-pipelines.yml exists, _detect_vcs() MUST return 'azure'. The GitLab workflow MUST contain 'codity config set-pat --provider gitlab'. The Azure workflow MUST contain 'codity config set-pat --provider azure'.",
3471+
"requirement_id": "REQ-354",
3472+
"type": "unit",
3473+
"verification_method": "pytest",
3474+
"input": "Scaffold.yml with gitlab/azure keyword; .gitlab-ci.yml present; azure-pipelines.yml present",
3475+
"expected_behavior": "Correct VCS detected; correct workflow file written; PAT setup command present",
3476+
"confidence": 0.95
3477+
},
3478+
{
3479+
"id": "TEST-356",
3480+
"title": "codity-ai-review Skill Is in Governance Skills Catalog",
3481+
"description": "specsmith.skills.governance.SKILLS MUST contain a SkillEntry with slug='codity-ai-review'. Its body MUST contain 'codity review --staged', 'codity login', 'codity init', 'codity scan --staged', 'codity test-gen --staged', 'codity doctor', 'specsmith integrate codity', 'HIGH severity', 'set-pat --provider gitlab', and 'set-pat --provider azure'. Its tags MUST include 'codity', 'ai-review', and 'pre-commit'. Its domain MUST be SkillDomain.GOVERNANCE.",
3482+
"requirement_id": "REQ-356",
3483+
"type": "unit",
3484+
"verification_method": "pytest",
3485+
"input": "from specsmith.skills.governance import SKILLS; find slug='codity-ai-review'",
3486+
"expected_behavior": "SkillEntry found; body and tags correct; domain GOVERNANCE",
3487+
"confidence": 0.95
3488+
},
3489+
{
3490+
"id": "TEST-357",
3491+
"title": "AGENTS.md Template Contains Codity.ai Pre-commit Rule",
3492+
"description": "The rendered agents.md.j2 template MUST contain a 'Codity.ai Code Review' section. The section MUST instruct agents to run 'codity review --staged' if codity doctor exits 0; MUST state that HIGH-severity findings block the commit; MUST mention MEDIUM-severity acknowledgement; MUST reference 'specsmith integrate codity'. The section MUST appear after the Session Governance Protocol section and before the project metadata footer.",
3493+
"requirement_id": "REQ-355",
3494+
"type": "unit",
3495+
"verification_method": "pytest",
3496+
"input": "Read src/specsmith/templates/agents.md.j2 directly; render via Jinja2 with minimal context",
3497+
"expected_behavior": "Template contains Codity section with review --staged, HIGH severity, MEDIUM, integrate codity",
3498+
"confidence": 0.95
34553499
}
34563500
]

‎README.md‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -202,7 +202,7 @@ be overwritten by the next sync.
202202
| `docs/requirements/yaml_governance.yml` | REQ-300..312 | YAML governance layer |
203203
| `docs/requirements/multiagent_compliance.yml` | REQ-313..320 | Multi-agent governance traceability |
204204
| `docs/requirements/dispatch.yml` | REQ-321..334 | Multi-agent DAG dispatcher |
205-
| `docs/requirements/overflow.yml` | REQ-335..353 | VCS ops, skills catalog, ESDB namespace, session governance, modern web types |
205+
| `docs/requirements/overflow.yml` | REQ-335..356 | VCS ops, skills catalog, ESDB namespace, session governance, modern web types, Codity.ai integration |
206206

207207
**Migration from Markdown-primary:**
208208
`scripts/migrate_governance_to_yaml.py` once to convert an existing project.
@@ -863,6 +863,25 @@ production LLM systems:
863863

864864
---
865865

866+
## Codity.ai AI Code Review Integration
867+
868+
specsmith can scaffold [Codity.ai](https://codity.ai) AI code review into any project:
869+
870+
```bash
871+
specsmith integrate codity --project-dir ./my-project
872+
```
873+
874+
This generates:
875+
- `.github/workflows/codity-review.yml` (GitHub Actions) or `.gitlab-ci-codity.yml` / `.azure-pipelines/codity-review.yml` depending on your VCS
876+
- `docs/codity-setup.md` — one-time setup checklist
877+
- Appends a TODO checklist to `LEDGER.md`
878+
879+
**AGENTS.md rule (REQ-355):** Projects with Codity configured SHOULD run `codity review --staged` before any commit touching production code. HIGH-severity findings are blocking; MEDIUM findings require inline acknowledgement.
880+
881+
See the `codity-ai-review` governance skill (`specsmith skill install codity-ai-review`) for the full CLI workflow reference.
882+
883+
---
884+
866885
## The specsmith Bootstrap
867886

868887
specsmith governs itself — the specsmith repo is a specsmith-managed project. Run `specsmith audit`

‎docs/ARCHITECTURE.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -883,3 +883,24 @@ Hard-resets the working tree to `origin/<branch>` via `git fetch` + `git reset -
883883
Same as `--discard` plus `git clean -fd` to remove all untracked files. Equivalent to a full workspace reset to remote state.
884884

885885
**Architecture invariant (I14):** `--force` and `--discard` flags MUST be used only when explicitly requested. They bypass safety guards intentionally designed to prevent accidental data loss. Agents MUST NOT invoke these flags without explicit user confirmation.
886+
887+
## 39. Codity.ai Integration — AI Code Review Adapter
888+
Source: `src/specsmith/integrations/codity.py`; `src/specsmith/skills/governance.py` (`codity-ai-review`)
889+
890+
`CodityAdapter` (REQ-354) scaffolds Codity.ai AI-code-review CI workflows into target projects via `specsmith integrate codity`. It detects the VCS host from `scaffold.yml` content and directory heuristics (`.gitlab-ci.yml`, `azure-pipelines.yml`) and generates the appropriate CI file:
891+
892+
| VCS host | Generated file |
893+
|---|---|
894+
| GitHub (default) | `.github/workflows/codity-review.yml` |
895+
| GitLab | `.gitlab-ci-codity.yml` |
896+
| Azure DevOps | `.azure-pipelines/codity-review.yml` |
897+
898+
All variants: install Codity CLI via `curl -fsSL https://cli.codity.ai/install.sh | sh`, run `codity review --staged`, require `CODITY_ACCESS_TOKEN` secret. GitLab/Azure additionally call `codity config set-pat --provider <vcs>` with a PAT.
899+
900+
`generate()` also writes `docs/codity-setup.md` (one-time setup checklist) and appends a TODO checklist to `LEDGER.md`.
901+
902+
The **`codity-ai-review`** governance skill (REQ-356) documents the full Codity.ai CLI workflow for agents: install, `codity login` (magic-link auth), `codity init`, daily commands (`review --staged`, `scan --staged`, `test-gen --staged`, `doctor`), VCS-specific PAT setup, and the AGENTS.md rule.
903+
904+
The **AGENTS.md template** (REQ-355) includes a conditional Codity section: projects with Codity configured SHOULD run `codity review --staged` before commits touching production code; HIGH-severity findings block the commit; MEDIUM findings require inline acknowledgement.
905+
906+
**Architecture invariant (I15):** The VCS-detection heuristic MUST default to `"github"` when no signals are present (scaffold.yml absent, no `.gitlab-ci.yml`, no `azure-pipelines.yml`). New VCS hosts require a new detection heuristic AND a corresponding workflow writer method.

‎docs/REQUIREMENTS.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2490,3 +2490,27 @@
24902490
- **Source:** ARCHITECTURE.md §Implemented Specsmith System
24912491
- **Test_Ids:** ['TEST-353']
24922492

2493+
## REQ-354. CodityAdapter Scaffolds AI Code Review CI Workflow
2494+
- **ID:** REQ-354
2495+
- **Title:** CodityAdapter Scaffolds AI Code Review CI Workflow
2496+
- **Description:** specsmith MUST provide a CodityAdapter registered as 'codity' in the integrations registry. CodityAdapter.generate() MUST detect the VCS host from scaffold.yml content ('gitlab' keyword → gitlab, 'azure' keyword → azure, else github) and from directory heuristics (.gitlab-ci.yml → gitlab, azure-pipelines.yml → azure). For github it MUST write .github/workflows/codity-review.yml; for gitlab it MUST write .gitlab-ci-codity.yml; for azure it MUST write .azure-pipelines/codity-review.yml. All variants MUST install the Codity CLI via the official install script, run 'codity review --staged', and require CODITY_ACCESS_TOKEN. GitLab and Azure variants MUST additionally call 'codity config set-pat --provider <vcs>'. generate() MUST also write docs/codity-setup.md (one-time setup checklist) and append a TODO checklist to LEDGER.md if it exists. The adapter MUST be discoverable via specsmith integrate codity.
2497+
- **Status:** implemented
2498+
- **Source:** ARCHITECTURE.md §39
2499+
- **Test_Ids:** ['TEST-354', 'TEST-355']
2500+
2501+
## REQ-355. AGENTS.md Template Includes Codity.ai Pre-commit Rule
2502+
- **ID:** REQ-355
2503+
- **Title:** AGENTS.md Template Includes Codity.ai Pre-commit Rule
2504+
- **Description:** The AGENTS.md Jinja2 template (agents.md.j2) MUST include a 'Codity.ai Code Review' section that instructs agents: if 'codity doctor' exits 0 (Codity is configured), run 'codity review --staged' before any commit touching production code; HIGH-severity findings are blocking; MEDIUM-severity findings require inline acknowledgement in the commit message; setup is via 'specsmith integrate codity --project-dir .'.
2505+
- **Status:** implemented
2506+
- **Source:** ARCHITECTURE.md §39
2507+
- **Test_Ids:** ['TEST-357']
2508+
2509+
## REQ-356. codity-ai-review Governance Skill in Skills Catalog
2510+
- **ID:** REQ-356
2511+
- **Title:** codity-ai-review Governance Skill in Skills Catalog
2512+
- **Description:** specsmith MUST include a 'codity-ai-review' SkillEntry in the governance domain skills catalog. The skill MUST document: Codity CLI install command (curl install script), codity login (magic-link browser auth), codity init (per-repo initialisation), daily commands (review --staged, scan --staged, test-gen --staged, doctor), the AGENTS.md blocking rule (HIGH severity = commit blocked, MEDIUM = acknowledgement required), CI integration via specsmith integrate codity, GitHub App setup, GitLab PAT setup (codity config set-pat --provider gitlab), and Azure DevOps PAT setup. The skill MUST be tagged with codity, ai-review, code-review, security, test-gen, ci, github, gitlab, azure, staged, pre-commit and discoverable via specsmith skill list.
2513+
- **Status:** implemented
2514+
- **Source:** ARCHITECTURE.md §39
2515+
- **Test_Ids:** ['TEST-356']
2516+

‎docs/TESTS.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2935,3 +2935,47 @@
29352935
- **Expected Behavior:** Each type has correct build tool; all five types in _TYPE_LABELS
29362936
- **Confidence:** 0.95
29372937

2938+
## TEST-354. CodityAdapter Generates GitHub Workflow by Default
2939+
- **ID:** TEST-354
2940+
- **Title:** CodityAdapter Generates GitHub Workflow by Default
2941+
- **Description:** CodityAdapter().generate(config, tmp_path) on a directory with no VCS signals MUST create .github/workflows/codity-review.yml containing 'codity review --staged', 'curl -fsSL https://cli.codity.ai/install.sh | sh', 'CODITY_ACCESS_TOKEN', and 'actions/checkout@v4'. It MUST also create docs/codity-setup.md. When LEDGER.md exists, a TODO checklist entry MUST be appended containing 'codity login' and 'codity doctor'. CodityAdapter().name MUST equal 'codity'.
2942+
- **Requirement ID:** REQ-354
2943+
- **Type:** unit
2944+
- **Verification Method:** pytest
2945+
- **Input:** CodityAdapter().generate(mock_config, tmp_path); tmp_path has no scaffold.yml or VCS hint files
2946+
- **Expected Behavior:** .github/workflows/codity-review.yml created; docs/codity-setup.md created; LEDGER.md appended; name == 'codity'
2947+
- **Confidence:** 0.95
2948+
2949+
## TEST-355. CodityAdapter Detects GitLab and Azure VCS from Scaffold or Directory
2950+
- **ID:** TEST-355
2951+
- **Title:** CodityAdapter Detects GitLab and Azure VCS from Scaffold or Directory
2952+
- **Description:** When scaffold.yml contains 'gitlab' (case-insensitive), _detect_vcs() MUST return 'gitlab' and generate() MUST write .gitlab-ci-codity.yml (not a GitHub workflow). When scaffold.yml contains 'azure', _detect_vcs() MUST return 'azure' and generate() MUST write .azure-pipelines/codity-review.yml. When .gitlab-ci.yml exists in the project root (no scaffold.yml), _detect_vcs() MUST return 'gitlab'. When azure-pipelines.yml exists, _detect_vcs() MUST return 'azure'. The GitLab workflow MUST contain 'codity config set-pat --provider gitlab'. The Azure workflow MUST contain 'codity config set-pat --provider azure'.
2953+
- **Requirement ID:** REQ-354
2954+
- **Type:** unit
2955+
- **Verification Method:** pytest
2956+
- **Input:** Scaffold.yml with gitlab/azure keyword; .gitlab-ci.yml present; azure-pipelines.yml present
2957+
- **Expected Behavior:** Correct VCS detected; correct workflow file written; PAT setup command present
2958+
- **Confidence:** 0.95
2959+
2960+
## TEST-356. codity-ai-review Skill Is in Governance Skills Catalog
2961+
- **ID:** TEST-356
2962+
- **Title:** codity-ai-review Skill Is in Governance Skills Catalog
2963+
- **Description:** specsmith.skills.governance.SKILLS MUST contain a SkillEntry with slug='codity-ai-review'. Its body MUST contain 'codity review --staged', 'codity login', 'codity init', 'codity scan --staged', 'codity test-gen --staged', 'codity doctor', 'specsmith integrate codity', 'HIGH severity', 'set-pat --provider gitlab', and 'set-pat --provider azure'. Its tags MUST include 'codity', 'ai-review', and 'pre-commit'. Its domain MUST be SkillDomain.GOVERNANCE.
2964+
- **Requirement ID:** REQ-356
2965+
- **Type:** unit
2966+
- **Verification Method:** pytest
2967+
- **Input:** from specsmith.skills.governance import SKILLS; find slug='codity-ai-review'
2968+
- **Expected Behavior:** SkillEntry found; body and tags correct; domain GOVERNANCE
2969+
- **Confidence:** 0.95
2970+
2971+
## TEST-357. AGENTS.md Template Contains Codity.ai Pre-commit Rule
2972+
- **ID:** TEST-357
2973+
- **Title:** AGENTS.md Template Contains Codity.ai Pre-commit Rule
2974+
- **Description:** The rendered agents.md.j2 template MUST contain a 'Codity.ai Code Review' section. The section MUST instruct agents to run 'codity review --staged' if codity doctor exits 0; MUST state that HIGH-severity findings block the commit; MUST mention MEDIUM-severity acknowledgement; MUST reference 'specsmith integrate codity'. The section MUST appear after the Session Governance Protocol section and before the project metadata footer.
2975+
- **Requirement ID:** REQ-355
2976+
- **Type:** unit
2977+
- **Verification Method:** pytest
2978+
- **Input:** Read src/specsmith/templates/agents.md.j2 directly; render via Jinja2 with minimal context
2979+
- **Expected Behavior:** Template contains Codity section with review --staged, HIGH severity, MEDIUM, integrate codity
2980+
- **Confidence:** 0.95
2981+

0 commit comments

Comments
 (0)