feat: add Claude Code and Cursor plugins for AIDLC methodology by rsmets · Pull Request #222 · awslabs/aidlc-workflows

rsmets · 2026-04-28T22:13:21Z

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 reads aidlc-rules/ and produces both plugin packages. Supports --target cc|cursor|all for building independently.

plugins/claude-code-aidlc/ (44 files) — Claude Code plugin with:

Component	Count	Description
Orchestrator agent	1	Drives the three-phase workflow, detects phase from workspace
Slash commands	4	`/aidlc`, `/aidlc:inception`, `/aidlc:construction`, `/aidlc:operations`
Skills	7	Core workflow, 3 phase skills, common rules, 2 opt-in extensions
Bundled rule references	29	Byte-identical copies of canonical rule-detail files

plugins/cursor-aidlc/ (33 files) — Cursor .mdc rule bundle with:

Component	Detail
Orchestrator rule	`alwaysApply: true` — loaded on every interaction
Core workflow rule	Cursor-specific path-resolution transform
Phase/common/extension rules	29 `.mdc` files with Agent Requested frontmatter (description-only)

Modified files

.github/workflows/ci.yml — added plugin-sync job that regenerates both plugins and fails via git diff --exit-code if committed output is stale
.github/labeler.yml — added plugin label for plugins/**
.github/CODEOWNERS — added plugins/ ownership (@awslabs/aidlc-admins @awslabs/aidlc-maintainers)
AGENTS.md — added both plugin directories and the generator script to the repo structure section
README.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/3
CONTRIBUTING.md — added section explaining that plugins/ is generated content and must not be edited directly

How the generator works

Reads aidlc-rules/VERSION and stamps it into both plugin packages
For Claude Code: copies rule-detail files into skills/*/references/ directories; emits orchestrator agent, commands, and SKILL.md files from embedded templates
For Cursor: wraps each rule-detail file in .mdc frontmatter with a description tuned for Cursor's Agent Requested mechanism; emits an orchestrator rule with alwaysApply: true
Transforms core-workflow.md path-resolution differently for each target (plugin skill references in CC, sibling rule paths in Cursor)
Copies the aidlc-rules/.markdownlint-cli2.yaml overrides into each plugin directory so generated content passes the repo's markdown linter

User 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 → cat rule into .mdc file → copy rule-details. Multi-step, error-prone.

After

Claude Code (local development):

claude --plugin-dir ./plugins/claude-code-aidlc

Then /aidlc to 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

I have reviewed the contributing guidelines
I have performed a self-review of this change
Changes have been tested
Changes are documented

Test Plan

Run python scripts/build-plugins.py && git diff --exit-code plugins/ — confirms idempotent generation for both plugins
Run python scripts/build-plugins.py --target cc — produces only plugins/claude-code-aidlc/
Run python scripts/build-plugins.py --target cursor — produces only plugins/cursor-aidlc/
Run npx markdownlint-cli2 "plugins/**/*.md" — all generated markdown passes lint
Verify plugins/claude-code-aidlc/.claude-plugin/plugin.json version matches aidlc-rules/VERSION
Verify Cursor .mdc files have correct frontmatter (alwaysApply: true only on orchestrator; all others have description set, alwaysApply: false)
Install CC plugin locally with claude --plugin-dir ./plugins/claude-code-aidlc and run /aidlc — welcome message appears
Copy Cursor rules into a project's .cursor/rules/ and verify the orchestrator activates in Cursor
Verify CI plugin-sync job passes

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

* 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>

Copilot

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.py to generate both plugin targets from aidlc-rules/.
Adds generated plugin outputs under plugins/claude-code-aidlc/ and plugins/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.

Copilot · 2026-04-28T22:59:46Z

+**Version**: {version}
+**Source of truth**: `aidlc-rules/` in this repository
+**Generator**: `scripts/build-cc-plugin.py`
+


plugin_readme() template still says the generator is scripts/build-cc-plugin.py, but the repository only contains scripts/build-plugins.py. This will generate incorrect instructions in the Claude Code plugin README; update the template to reference scripts/build-plugins.py (and regenerate plugins).

Copilot · 2026-04-28T22:59:46Z

+
+**Version**: 0.1.8
+**Source of truth**: `aidlc-rules/` in this repository
+**Generator**: `scripts/build-cc-plugin.py`


This README claims the plugin is generated by scripts/build-cc-plugin.py, but the repository generator is scripts/build-plugins.py. Update the generated output (and generator template) so the README points at the actual script.

Suggested change

**Generator**: `scripts/build-cc-plugin.py`

**Generator**: `scripts/build-plugins.py`

Copilot · 2026-04-28T22:59:47Z

+Once installed, the `aidlc/aidlc-orchestrator.mdc` rule is set to
+`alwaysApply: true`, so Cursor loads it on every interaction. To start a
+workflow, just describe the work:


This refers to the orchestrator as aidlc/aidlc-orchestrator.mdc, but in this bundle the file is at rules/aidlc-orchestrator.mdc (and when copied into a project it will be .cursor/rules/aidlc-orchestrator.mdc). Update the path to match the actual file location to avoid confusing installation/usage.

Copilot · 2026-04-28T22:59:47Z

+### Plans
+Documents with checkboxes and questions that guide execution.
+- Located in `aidlc-docs/plans/`
+- Examples: `story-generation-plan.md`, `unit-of-work-plan.md`


This glossary says plan documents are located in aidlc-docs/plans/, but the stage rules in this bundle consistently write plans under aidlc-docs/inception/plans/ and aidlc-docs/construction/plans/. Align this description with the actual paths used elsewhere to avoid sending users/tools to a nonexistent directory.

Copilot · 2026-04-28T22:59:47Z

+Do not edit files in this directory directly. Edit the canonical source in
+`aidlc-rules/` at the repository root, then regenerate:
+
+```bash
+python scripts/build-cc-plugin.py
+```


The generated README instructions here still tell users to run python scripts/build-cc-plugin.py, but that script does not exist (the generator is scripts/build-plugins.py). Update this text (via the generator template) so contributors run the correct command, then regenerate the plugin output.

Copilot · 2026-04-28T22:59:47Z

+Do not edit files in this directory directly. Edit the canonical source in
+`aidlc-rules/` at the repository root, then regenerate:
+
+```bash
+python scripts/build-cc-plugin.py
+```


Contributing section instructs running python scripts/build-cc-plugin.py, but that script doesn't exist in this repo (generator is scripts/build-plugins.py). Since plugins/ is generated content, fix this via the generator template and regenerate.

Copilot · 2026-04-28T22:59:47Z

+### Implementation Pattern
+```markdown
+## Workflow Visualization
+
+### Mermaid Diagram (if syntax valid)
+```mermaid
+[validated diagram content]
+```
+
+### Text Alternative (always include)
+```
+Phase 1: INCEPTION


The “Implementation Pattern” example nests fenced code blocks using the same triple-backtick fence (markdown containing mermaid), which breaks Markdown rendering and can confuse both humans and tooling. Use a longer outer fence (e.g., 4 backticks) or indent/escape inner fences so the example is syntactically valid.

Copilot · 2026-04-28T22:59:48Z

+### Implementation Pattern
+```markdown
+## Workflow Visualization
+
+### Mermaid Diagram (if syntax valid)
+```mermaid
+[validated diagram content]
+```
+
+### Text Alternative (always include)
+```
+Phase 1: INCEPTION
+- Stage 1: Workspace Detection (COMPLETED)
+- Stage 2: Requirements Analysis (COMPLETED)
+[continue with text representation]
+```


The “Implementation Pattern” example nests fenced code blocks with the same triple-backtick fence (markdown containing mermaid), which makes the Markdown invalid and the example render incorrectly. Use a longer outer fence (e.g., 4 backticks) or indent/escape the inner fences.

Copilot · 2026-04-28T22:59:48Z

+
+### Plans
+Documents with checkboxes and questions that guide execution.
+- Located in `aidlc-docs/plans/`


This glossary states plans live in aidlc-docs/plans/, but other rules in the plugin store plans under aidlc-docs/inception/plans/ and aidlc-docs/construction/plans/. Update this to reflect the actual plan locations to prevent broken references.

Suggested change

- Located in `aidlc-docs/plans/`

- Located in phase-specific plan directories such as `aidlc-docs/inception/plans/` and `aidlc-docs/construction/plans/`

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>

rsmets requested review from a team, Kalindi-Dev, harmjeff, raj-jain-aws, scoropeza, scottschreckengaust and spraja08 April 28, 2026 22:13

rsmets requested a review from a team as a code owner April 28, 2026 22:13

github-actions Bot added documentation Improvements or additions to documentation github labels Apr 28, 2026

rsmets changed the title ~~feat: add Claude Code and Cursor plugins for AIDLC methodology (#1)~~ feat: add Claude Code and Cursor plugins for AIDLC methodology Apr 28, 2026

MichaelWalker-git requested a review from Copilot April 28, 2026 22:55

Copilot started reviewing on behalf of MichaelWalker-git April 28, 2026 22:56 View session

Copilot AI reviewed Apr 28, 2026

View reviewed changes

rsmets requested a review from a team as a code owner April 28, 2026 23:01

github-actions Bot added the rules label Apr 28, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add Claude Code and Cursor plugins for AIDLC methodology#222

feat: add Claude Code and Cursor plugins for AIDLC methodology#222
rsmets wants to merge 2 commits intoawslabs:mainfrom
rsmets:main

rsmets commented Apr 28, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 28, 2026

Uh oh!

Copilot AI Apr 28, 2026

Uh oh!

Copilot AI Apr 28, 2026

Uh oh!

Copilot AI Apr 28, 2026

Uh oh!

Copilot AI Apr 28, 2026

Uh oh!

Copilot AI Apr 28, 2026

Uh oh!

Copilot AI Apr 28, 2026

Uh oh!

Copilot AI Apr 28, 2026

Uh oh!

Copilot AI Apr 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	Generator: `scripts/build-cc-plugin.py`
	Generator: `scripts/build-plugins.py`

	- Located in `aidlc-docs/plans/`
	- Located in phase-specific plan directories such as `aidlc-docs/inception/plans/` and `aidlc-docs/construction/plans/`

Conversation

rsmets commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

New files

Modified files

How the generator works

User experience

Before

After

Checklist

Test Plan

Acknowledgment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rsmets commented Apr 28, 2026 •

edited

Loading