create-agentic-pdlc 2.0.6 β 2.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +42 -49
- package/adapters/claude-code/skill.md +28 -12
- package/bin/cli.js +12 -4
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,88 +1,81 @@
|
|
|
1
1
|
# π€ Agentic PDLC Framework
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
> **Stop fighting your AI agents. Give them structure.**
|
|
7
|
-
|
|
8
|
-
**Agentic PDLC** is a lightweight, zero-dependency boilerplate that transforms chaotic AI coding into a deterministic, automated software assembly line.
|
|
3
|
+
> Do your AI agents build features that don't match the spec?
|
|
4
|
+
> Do you find bugs and architecture violations only at the end of the lifecycle?
|
|
5
|
+
> Are you the one manually moving cards across your board β every single time?
|
|
9
6
|
|
|
10
|
-
|
|
7
|
+
**Agentic PDLC** gives your agents a shared rulebook, a self-moving board, and a CI that won't let broken code reach production. One `npx` command to set up.
|
|
11
8
|
|
|
12
9
|
<div align="center">
|
|
13
10
|
<img src=".github/assets/agentic-pdlc-flow.svg" alt="Agentic PDLC Architecture Flow" width="100%">
|
|
14
11
|
</div>
|
|
15
12
|
|
|
13
|
+
Solo devs and small teams hit the same wall: one agent writes the spec, another implements it differently, a third reviews without knowing either. Agentic PDLC gives all of them a shared brief, automates the board, and puts a CI guard between your agents and production.
|
|
14
|
+
|
|
16
15
|
---
|
|
17
16
|
|
|
18
|
-
## β‘ Why
|
|
17
|
+
## β‘ Why it works
|
|
18
|
+
|
|
19
|
+
- πΊοΈ **A transparent lifecycle** β Every feature travels a Kanban board from Idea to Production. You always know where things are.
|
|
20
|
+
- π€ **A board that moves itself** β When you approve a spec, the card moves. When an agent opens a PR, the card moves. You just approve or reject.
|
|
21
|
+
- π§ **Agents that agree with each other** β One briefing (`AGENTS.md`), read by every agent. Claude, Jules, Gemini β all pulling in the same direction, without you copy-pasting context between tabs.
|
|
22
|
+
- π‘οΈ **Code that can't silently break production** β A CI auditor checks every PR for architecture violations before anything reaches your main branch. *(Maturity Model β coming soon)*
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## π Quick Start
|
|
27
|
+
|
|
28
|
+
Run this in the root of your project:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
npx create-agentic-pdlc
|
|
32
|
+
```
|
|
19
33
|
|
|
20
|
-
|
|
21
|
-
- π€ **Automated Handoffs**: Move cards across your GitHub board with labels. Brainstorm with Claude upstream, let Jules code downstream.
|
|
22
|
-
- π **Interactive Setup**: Run one `npx` command and let your favorite AI assistant scaffold the framework into your project interactively.
|
|
23
|
-
- π **Maturity Model**: A clear path from structured (Level 1) to semi-autonomous (Level 3) development. [Read the Agentic Maturity Model](docs/maturity-model.md).
|
|
34
|
+
The CLI sets up your GitHub board, labels, and workflows, then hands over to your AI assistant to finish the configuration interactively. No YAML editing. No manual config.
|
|
24
35
|
|
|
25
36
|
---
|
|
26
37
|
|
|
27
|
-
## ποΈ How It Works
|
|
38
|
+
## ποΈ How It Works
|
|
28
39
|
|
|
29
|
-
The
|
|
40
|
+
The framework splits work into two phases:
|
|
30
41
|
|
|
31
|
-
###
|
|
32
|
-
|
|
42
|
+
### 1. You + AI: Idea β Spec
|
|
43
|
+
Use conversational AI (e.g., **Claude Code**, **Gemini CLI**) as your brainstorming partner. Together, you flesh out user stories, acceptance criteria, and technical specifications until they are solid.
|
|
33
44
|
|
|
34
|
-
###
|
|
35
|
-
Once the spec
|
|
45
|
+
### 2. Your agents: Spec β Production
|
|
46
|
+
Once you approve the spec, autonomous implementation agents (e.g., **Jules**, **Sweep**, **Copilot Workspace**) pick up the task. The board moves automatically; the CI auditor guards the main branch.
|
|
36
47
|
|
|
37
48
|
---
|
|
38
49
|
|
|
39
|
-
## π€
|
|
50
|
+
## π€ Works with every AI assistant
|
|
40
51
|
|
|
41
|
-
|
|
52
|
+
One shared brief (`AGENTS.md`). Every agent reads it.
|
|
42
53
|
|
|
43
54
|
| AI Assistant | Instruction File | How it Integrates |
|
|
44
55
|
|:---|:---|:---|
|
|
45
56
|
| **Claude Code** | `CLAUDE.md` + Claude Skill | Uses `adapters/claude-code/skill.md` *(Includes Auto-Setup Mode)* |
|
|
57
|
+
| **Gemini CLI** | `AGENTS.md` | Reads the rulebook natively |
|
|
46
58
|
| **Cursor** | `.cursor/rules/*.md` | Uses `adapters/cursor/rules.md` |
|
|
47
59
|
| **GitHub Copilot** | `.github/copilot-instructions.md` | Uses `templates/.github/copilot-instructions.md` |
|
|
48
|
-
| **Codex / Antigravity** | `AGENTS.md` | Reads the
|
|
49
|
-
|
|
50
|
-
*No matter which AI you pair with, they will all share the exact same context.*
|
|
60
|
+
| **Codex / Antigravity** | `AGENTS.md` | Reads the rulebook natively |
|
|
51
61
|
|
|
52
62
|
---
|
|
53
63
|
|
|
54
|
-
##
|
|
64
|
+
## π¦ What you get
|
|
55
65
|
|
|
56
|
-
|
|
66
|
+
After setup, your project has:
|
|
57
67
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
βββ docs/
|
|
62
|
-
β βββ pdlc.md β The PDLC pipeline defining board columns and IDs.
|
|
63
|
-
βββ .github/
|
|
64
|
-
βββ workflows/
|
|
65
|
-
βββ project-automation.yml β Automates GitHub Project card movement.
|
|
66
|
-
βββ agent-trigger.yml β Wakes up your agent upon `spec:approved`.
|
|
67
|
-
βββ ci.yml β The Sentinel enforcing invariants and tests.
|
|
68
|
-
```
|
|
68
|
+
- **`AGENTS.md`** β The shared brief every agent reads. Your rules, once.
|
|
69
|
+
- **`docs/pdlc.md`** β Your pipeline map: board columns, IDs, and who does what.
|
|
70
|
+
- **`.github/workflows/`** β Three automations: board moves itself, agent wakes on spec approval, CI audits every PR.
|
|
69
71
|
|
|
70
72
|
---
|
|
71
73
|
|
|
72
|
-
##
|
|
73
|
-
|
|
74
|
-
Ready to build at the speed of thought? Scaffold the entire framework interactively without copy-pasting code!
|
|
75
|
-
|
|
76
|
-
Simply run our installer in the root of your project:
|
|
77
|
-
|
|
78
|
-
```bash
|
|
79
|
-
npx create-agentic-pdlc
|
|
80
|
-
```
|
|
74
|
+
## β€οΈ Contributing
|
|
81
75
|
|
|
82
|
-
|
|
76
|
+
We welcome improvements from solo founders and AI engineers! Please check our **[Contributing Guidelines](CONTRIBUTING.md)** on how to submit PRs, add new AI platform adapters, or improve the documentation.
|
|
83
77
|
|
|
84
78
|
---
|
|
85
79
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
We welcome improvements from other solo-founders and AI-engineers! Please check our **[Contributing Guidelines](CONTRIBUTING.md)** on how to submit PRs, add new AI platform adapters, or improve the documentation.
|
|
80
|
+
[](https://opensource.org/licenses/MIT)
|
|
81
|
+
[](http://makeapullrequest.com)
|
|
@@ -19,21 +19,37 @@ Specifically, check for:
|
|
|
19
19
|
- `.github/workflows/pdlc-health-check.yml`
|
|
20
20
|
|
|
21
21
|
If any of these files are missing, you are in **Setup Mode**. Do not proceed with feature requests until setup is complete.
|
|
22
|
+
|
|
22
23
|
1. **Language Detection:** Analyze the user's previous prompts and preferred language. Conduct this entire Setup Mode and ask all your interactive questions in that same language.
|
|
23
24
|
2. Acknowledge that the framework is not yet set up.
|
|
24
|
-
3.
|
|
25
|
-
-
|
|
26
|
-
-
|
|
25
|
+
3. **Pre-filled Context:** Before asking any questions, read the following files if they exist:
|
|
26
|
+
- `.agentic-pdlc/cli-context.json` β written by the CLI. Contains `projectName`, `repoOwner`, `repoName`. Use these values directly and skip the corresponding questions.
|
|
27
|
+
- `.agentic-pdlc/templates/docs/pdlc.md` β the CLI pre-fills PROJECT_ID, STATUS_FIELD_ID, REPO_OWNER, REPO_NAME, and all 9 column option IDs. If none of the values still contain `{{...}}` placeholders, skip the entire Board IDs question group.
|
|
28
|
+
4. Interactively ask the user only for the **missing values**, **one group at a time**:
|
|
29
|
+
- **Project basics:** Project Name (skip if present in `cli-context.json`), Description, Technical Stack/Structure. **Do not ask for GitHub Username** β use `repoOwner` from `cli-context.json` directly for CODEOWNERS.
|
|
30
|
+
- **Commands:** In the user's detected language, ask for each command with its purpose and concrete examples:
|
|
31
|
+
- **Test command** β the command that runs automated tests (e.g. `npm test`, `pytest`, `go test ./...`, `./gradlew test`) β reply "none" if not applicable.
|
|
32
|
+
- **Lint command** β the command that checks code quality/style (e.g. `npm run lint`, `ruff check .`, `eslint .`, `golangci-lint run`) β reply "none" if not applicable.
|
|
33
|
+
- **Build command** β the command that compiles or bundles the project (e.g. `npm run build`, `tsc`, `go build ./...`, `./gradlew build`) β reply "none" if not applicable.
|
|
27
34
|
- **Invariants:** Critical business rules agents must never violate (e.g. Human-in-the-loop).
|
|
28
|
-
- **Board IDs:**
|
|
29
|
-
- **Architecture
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
35
|
+
- **Board IDs:** Skip entirely if `.agentic-pdlc/templates/docs/pdlc.md` is already pre-filled (no `{{...}}` placeholders). Only ask if placeholders remain.
|
|
36
|
+
- **Architecture Audit (CI):** Ask: *"Does your project use automated architecture auditing (a CI job that creates issues with the `architecture-violation` label)?"* Present the options:
|
|
37
|
+
- a) **I don't use it, but I want to configure it** β *Makes the CI/CD pipeline more robust via Gemini Code Assist.* β Guide the user through configuration.
|
|
38
|
+
- b) **Not now** β *Leave it commented to activate later.* β Job remains commented in `project-automation.yml`.
|
|
39
|
+
- c) **Yes, activate** β *Uncomment the `move-violation-to-board` job in `project-automation.yml`.* β Activate immediately.
|
|
40
|
+
- **QA Agent:** Ask: *"Do you want to use a QA agent to verify PRs automatically before Code Review?"* Present the options:
|
|
41
|
+
- a) **No (Variant A)** β *PRs go straight to Code Review. Standard and simpler.*
|
|
42
|
+
- b) **Yes (Variant B), but I need help configuring it** β *PRs pass through a QA Agent before being reviewed. Requires a QA Agent (e.g., QAWolf).* β Guide the user through configuration.
|
|
43
|
+
- c) **Yes (Variant B), I already have it configured** β *PRs pass through a QA Agent before being reviewed.* β Activate Variant B immediately: change `STATUS_CODE_REVIEW_PR` to `STATUS_TESTING` in the `move-card-on-pr-open` job and uncomment the `move-card-on-qa-pass` job in `project-automation.yml`.
|
|
44
|
+
- **Implementation Agent:** Ask: *"Do you use an autonomous implementation agent? (It implements the features you approve for development)"* Present the options:
|
|
45
|
+
- a) **No** β *No autonomous implementation agent.*
|
|
46
|
+
- b) **@google-labs-jules** β *Jules (recommended if you don't have one).*
|
|
47
|
+
- c) **Other** β *Enter the agent's handle.*
|
|
48
|
+
5. Generate and write the missing files replacing the `{{SCREAMING_SNAKE_CASE}}` placeholders using the templates in `.agentic-pdlc/templates/`.
|
|
49
|
+
6. Offer to run the `gh` commands for labels (`spec:approved`, `pr:in-review`, `pr:approved`, `architecture-violation`).
|
|
50
|
+
7. **IMPORTANT:** Delete this setup prompt file (`.agentic-setup.md`, `.agentic-setup-prompt.md`, or `.agentic-pdlc/SETUP_PROMPT.md`) using only `rm <file>` β **do NOT run `git add` or any other git command**. This file was never committed and does not exist in the git index. Delete it **before** the commit step so it is never accidentally included in the repository history.
|
|
51
|
+
8. Commit everything with the message: `chore: setup agentic-pdlc framework`.
|
|
52
|
+
9. Conclude Setup Mode.
|
|
37
53
|
|
|
38
54
|
---
|
|
39
55
|
|
package/bin/cli.js
CHANGED
|
@@ -297,10 +297,10 @@ async function runSetup() {
|
|
|
297
297
|
if (fs.existsSync(pdlcDest)) {
|
|
298
298
|
let pdlcContent = fs.readFileSync(pdlcDest, 'utf8');
|
|
299
299
|
|
|
300
|
-
if (projectId) pdlcContent = pdlcContent.replace(
|
|
301
|
-
if (statusFieldId) pdlcContent = pdlcContent.replace(
|
|
302
|
-
pdlcContent = pdlcContent.replace(
|
|
303
|
-
pdlcContent = pdlcContent.replace(
|
|
300
|
+
if (projectId) pdlcContent = pdlcContent.replace(/\{\{PROJECT_ID\}\}/g, () => projectId);
|
|
301
|
+
if (statusFieldId) pdlcContent = pdlcContent.replace(/\{\{STATUS_FIELD_ID\}\}/g, () => statusFieldId);
|
|
302
|
+
pdlcContent = pdlcContent.replace(/\{\{REPO_OWNER\}\}/g, () => repoOwner);
|
|
303
|
+
pdlcContent = pdlcContent.replace(/\{\{REPO_NAME\}\}/g, () => repoName);
|
|
304
304
|
|
|
305
305
|
if (Object.keys(optionMap).length > 0) {
|
|
306
306
|
pdlcContent = pdlcContent.replace(/\{\{ID_IDEA\}\}/g, optionMap["π‘ Idea"] || 'MISSING_ID');
|
|
@@ -319,6 +319,14 @@ async function runSetup() {
|
|
|
319
319
|
}
|
|
320
320
|
}
|
|
321
321
|
|
|
322
|
+
// Write CLI context for the agent to consume in Setup Mode
|
|
323
|
+
try {
|
|
324
|
+
const cliContextPath = path.join(targetDir, '.agentic-pdlc', 'cli-context.json');
|
|
325
|
+
fs.writeFileSync(cliContextPath, JSON.stringify({ projectName, repoOwner, repoName }, null, 2));
|
|
326
|
+
} catch (err) {
|
|
327
|
+
// Non-fatal β agent will ask for the values instead
|
|
328
|
+
}
|
|
329
|
+
|
|
322
330
|
// Handle the specific setup instructions target
|
|
323
331
|
const claudeSetupSrc = path.join(sourceDir, 'adapters', 'claude-code', 'skill.md');
|
|
324
332
|
const cursorSetupSrc = path.join(sourceDir, 'adapters', 'cursor', 'rules.md');
|