feat: add Claude Code and Cursor plugins for AIDLC methodology#222
feat: add Claude Code and Cursor plugins for AIDLC methodology#222rsmets wants to merge 3 commits into
Conversation
* feat: add Claude Code plugin for AIDLC methodology Replace the manual setup flow (download zip, copy core-workflow.md to CLAUDE.md, copy rule-details) with a first-class Claude Code plugin installable via `claude plugin install`. The plugin provides: - An orchestrator agent that drives the three-phase workflow - Slash commands: /aidlc, /aidlc:inception, /aidlc:construction, /aidlc:operations - 7 skills bundling all rule-detail content with progressive disclosure - Opt-in extension skills for security baseline and property-based testing A stdlib-only Python generator (scripts/build-cc-plugin.py) produces the entire plugin from the canonical aidlc-rules/ source files, with a CI job that enforces zero drift between source and generated output. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * chore: remove brainstorm and plan docs from branch These artifacts informed the PR description and are not needed as committed files in the repository. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * readme * feat: add Cursor plugin alongside Claude Code plugin Extend the plugin generator to produce a Cursor rules bundle in addition to the Claude Code plugin. Cursor doesn't have a native "plugin" format like CC, but it supports Remote Rules via GitHub — users can install the whole rule set in a single Settings UI step. Changes: - Rename scripts/build-cc-plugin.py → scripts/build-plugins.py - Add build_cursor_plugin() that emits plugins/cursor-aidlc/ with the rule tree as .mdc files preserving source directory structure - Orchestrator rule uses alwaysApply: true; all other rules are Agent Requested (description-only) for context efficiency - Cursor-specific path-resolution transform for core-workflow.md - Add --target flag to build cc or cursor independently - README: add Remote Rules (GitHub) as Cursor Option 1 (recommended) - CI: update plugin-sync job to run the renamed script - CONTRIBUTING + AGENTS.md: document both generated plugins Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * fix: flatten Cursor plugin structure and fix README accuracy Move .mdc files from plugins/cursor-aidlc/.cursor/rules/aidlc/ to plugins/cursor-aidlc/rules/ for a cleaner manual copy path. Update README to recommend the copy method as primary since Remote Rules produces deeply nested import paths in a monorepo. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> --------- Co-authored-by: Ray Smets <rsmets@amazon.com> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
rsmets
requested review from
a team,
Kalindi-Dev,
harmjeff,
raj-jain-aws,
scoropeza,
scottschreckengaust and
spraja08
github-actions
Bot
added
documentation
rsmets
changed the title
There was a problem hiding this comment.
Pull request overview
Adds first-class, generated plugin bundles for the AI-DLC methodology (Claude Code + Cursor) and wires CI/docs to make plugins the recommended installation path while preventing drift from aidlc-rules/.
Changes:
- Introduces
scripts/build-plugins.pyto generate both plugin targets fromaidlc-rules/. - Adds generated plugin outputs under
plugins/claude-code-aidlc/andplugins/cursor-aidlc/. - Updates CI and docs to recommend plugins and enforce plugin/source synchronization.
Reviewed changes
Copilot reviewed 85 out of 85 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| scripts/build-plugins.py | Generator that produces Claude Code + Cursor plugin artifacts from aidlc-rules/. |
| plugins/claude-code-aidlc/** | Generated Claude Code plugin (agents/commands/skills/references/manifest/docs). |
| plugins/cursor-aidlc/** | Generated Cursor .mdc rules bundle + docs + markdownlint overrides. |
| .github/workflows/ci.yml | Adds plugin-sync job to regenerate plugins and fail on drift. |
| .github/labeler.yml | Adds plugin label targeting plugins/**. |
| .github/CODEOWNERS | Adds ownership for plugins/. |
| README.md | Promotes plugin-based install paths for Cursor and Claude Code. |
| CONTRIBUTING.md | Documents that plugins/ is generated and how to regenerate. |
| AGENTS.md | Updates repo structure to include plugins and generator script. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
The orchestrator agents previously used descriptive language ("guide the
user", numbered how-to steps) that the LLM could rationalize away when
a task seemed simple. In practice this led to agents skipping the
welcome message, audit.md, aidlc-state.md, Workspace Detection, and
per-stage approvals while still claiming the work was AIDLC-driven.
This change replaces descriptive language with enforcement language and
adds explicit violation callouts:
- core-workflow.md: add a Pre-Flight Hard Gate block at the top of the
authoritative rules file with 7 required actions before any substantive
response; add an "Adaptive Depth vs. Mandatory Steps" clause clarifying
that the workflow is adaptive in depth, not in mandatory steps.
- Claude Code orchestrator agent: rewrite with a First-Turn Hard Gate,
per-stage approval gate, question-format gate, continuous audit-trail
requirements, self-audit checklist, and an enumerated "What Counts as
a Violation" list targeting each specific failure mode.
- Cursor orchestrator rule: apply the same enforcement text, adapted to
.mdc sibling-rule references.
- build-plugins.py: regenerate both plugins with the new orchestrator
text and the updated core-workflow.md.
Adaptive depth (minimal / standard / comprehensive) is preserved. What
is no longer permitted is skipping stages, rolling multiple stages under
one approval, or asking clarifying questions in chat instead of question
files.
Co-authored-by: Ray Smets <rsmets@amazon.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
- Correct generator script name references (build-cc-plugin.py → build-plugins.py) - Fix glossary plan paths to match actual phase-specific locations - Escape nested mermaid fence in content-validation example - Update Cursor README orchestrator path to .cursor/rules/ prefix Canonical sources updated; plugins regenerated via scripts/build-plugins.py.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 88 out of 88 changed files in this pull request and generated 6 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| **Adaptive Phase**: Always executes. Detail level adapts to problem complexity. | ||
|
|
||
| **See [depth-levels.md](../common/depth-levels.md) for adaptive depth explanation** |
There was a problem hiding this comment.
This file links to ../common/depth-levels.md, but the Cursor bundle ships ../common/depth-levels.mdc. As written, a consumer (or the agent following instructions) will try to open a nonexistent file. Update the link (and ideally the generator) to reference the .mdc filename (or use extensionless links) consistently across the Cursor rules.
|
|
||
| ## Step 4: Note Adaptive Detail | ||
|
|
||
| **See [depth-levels.md](../common/depth-levels.md) for adaptive depth explanation** |
There was a problem hiding this comment.
This file links to ../common/depth-levels.md, but the Cursor rule bundle contains ../common/depth-levels.mdc. Adjust the link (and generator rewrite rules if applicable) so the referenced file name matches what’s actually generated, otherwise the workflow instructions point to a missing file.
| 1. **LOAD** `common/ascii-diagram-standards.md` | ||
| 2. **VALIDATE** each diagram: | ||
| - Count characters per line (all lines MUST be same width) | ||
| - Use ONLY: `+` `-` `|` `^` `v` `<` `>` and spaces | ||
| - NO Unicode box-drawing characters | ||
| - Spaces only (NO tabs) | ||
| 3. **TEST** alignment by verifying box corners align vertically | ||
|
|
||
| **See `common/ascii-diagram-standards.md` for patterns and validation checklist.** |
There was a problem hiding this comment.
The instructions here reference common/ascii-diagram-standards.md, but in this Cursor bundle the rule file is common/ascii-diagram-standards.mdc. To avoid failed loads / broken references, update these file references (and the generator templates) to use the .mdc extension consistently for Cursor rules.
| ## Error Handling | ||
| If artifacts are missing or corrupted during session resumption, see [error-handling.md](error-handling.md) for guidance on recovery procedures. No newline at end of file |
There was a problem hiding this comment.
The error-handling reference/link uses error-handling.md, but the rule file shipped in this bundle is error-handling.mdc. Update the link/filename so it resolves correctly within the Cursor rules directory.
| 1. **Create or append to `aidlc-docs/audit.md`**: Log the user's complete raw input with ISO-8601 timestamp per the format in the "Prompts Logging Requirements" section below. If the file does not exist, create it. NEVER overwrite; always append. | ||
| 2. **Resolve the rule-details directory**: Probe the four paths listed under "MANDATORY: Rule Details Loading" below and record the resolved path in `audit.md`. | ||
| 3. **Load common rules** from the resolved rule-details directory: `common/process-overview.md`, `common/session-continuity.md`, `common/content-validation.md`, `common/question-format-guide.md`. | ||
| 4. **Display the welcome message** from `common/welcome-message.md` (first turn only — do not re-display on subsequent turns). |
There was a problem hiding this comment.
In this Cursor bundle the actual rule files are .mdc, but the pre-flight steps instruct loading common/*.md files. Even though a later note explains the mapping, this is easy to follow incorrectly and can lead to failed file loads. Prefer updating these references to the real .mdc filenames (or removing extensions entirely) so the instructions are self-consistent.
| - Use the standardized 2-option completion message defined in the stage's | ||
| rule file. Do NOT invent 3-option menus. | ||
| - Log the approval prompt in `audit.md` BEFORE asking; log the user's |
There was a problem hiding this comment.
This section mandates a “standardized 2-option completion message” and forbids 3-option menus, but several stage templates in this same bundle explicitly include conditional third options (e.g., “Add User Stories” / “Add Units Generation”). Align the orchestrator guidance with the stage rule definitions (e.g., ‘use exactly the options defined by the current stage’s rule file’) to avoid contradictory instructions.
Summary
Add native plugin packages for Claude Code and Cursor so users can install the AIDLC methodology in one step instead of manually downloading a zip, copying rule files, and overwriting their project config. Both packages are generated from the canonical
aidlc-rules/source by a single stdlib-only Python script, and CI enforces zero drift between source and generated output.Changes
New files
scripts/build-plugins.py— generator script (stdlib-only Python, no dependencies) that readsaidlc-rules/and produces both plugin packages. Supports--target cc|cursor|allfor building independently.plugins/claude-code-aidlc/(44 files) — Claude Code plugin with:/aidlc,/aidlc:inception,/aidlc:construction,/aidlc:operationsplugins/cursor-aidlc/(33 files) — Cursor.mdcrule bundle with:alwaysApply: true— loaded on every interaction.mdcfiles with Agent Requested frontmatter (description-only)Modified files
.github/workflows/ci.yml— addedplugin-syncjob that regenerates both plugins and fails viagit diff --exit-codeif committed output is stale.github/labeler.yml— addedpluginlabel forplugins/**.github/CODEOWNERS— addedplugins/ownership (@awslabs/aidlc-admins @awslabs/aidlc-maintainers)AGENTS.md— added both plugin directories and the generator script to the repo structure sectionREADME.md— added recommended plugin-based install paths for both Claude Code (Option 1) and Cursor (Option 1), demoting the manual zip-and-copy instructions to Option 2/3CONTRIBUTING.md— added section explaining thatplugins/is generated content and must not be edited directlyHow the generator works
aidlc-rules/VERSIONand stamps it into both plugin packagesskills/*/references/directories; emits orchestrator agent, commands, and SKILL.md files from embedded templates.mdcfrontmatter with a description tuned for Cursor's Agent Requested mechanism; emits an orchestrator rule withalwaysApply: truecore-workflow.mdpath-resolution differently for each target (plugin skill references in CC, sibling rule paths in Cursor)aidlc-rules/.markdownlint-cli2.yamloverrides into each plugin directory so generated content passes the repo's markdown linterUser experience
Before
Claude Code: Download zip → extract →
cp core-workflow.md ./CLAUDE.md(overwrites existing config) →cp -R aws-aidlc-rule-details/ .aidlc-rule-details/(pollutes workspace). No update path.Cursor: Download zip → extract → create frontmatter wrapper →
catrule into.mdcfile → copy rule-details. Multi-step, error-prone.After
Claude Code (local development):
Then
/aidlcto start the workflow.Cursor (recommended):
cp -R plugins/cursor-aidlc/rules/* /path/to/project/.cursor/rules/Open the project — the orchestrator rule loads automatically.
Both paths preserve the user's existing project config and keep methodology files out of the workspace root.
Checklist
Test Plan
python scripts/build-plugins.py && git diff --exit-code plugins/— confirms idempotent generation for both pluginspython scripts/build-plugins.py --target cc— produces onlyplugins/claude-code-aidlc/python scripts/build-plugins.py --target cursor— produces onlyplugins/cursor-aidlc/npx markdownlint-cli2 "plugins/**/*.md"— all generated markdown passes lintplugins/claude-code-aidlc/.claude-plugin/plugin.jsonversion matchesaidlc-rules/VERSION.mdcfiles have correct frontmatter (alwaysApply: trueonly on orchestrator; all others havedescriptionset,alwaysApply: false)claude --plugin-dir ./plugins/claude-code-aidlcand run/aidlc— welcome message appears.cursor/rules/and verify the orchestrator activates in Cursorplugin-syncjob passesAcknowledgment
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.