@aicgen/aicgen 1.0.5 → 1.1.1

package/data/version.json

@@ -1,6 +1,6 @@
 {
   "version": "1.0.0",
-  "lastUpdated": "2026-01-15",
+  "lastUpdated": "2026-05-14",
   "totalGuidelines": 99,
   "categories": {
     "Language": 39,

package/data/workflows/README.md

@@ -0,0 +1,51 @@
+# SDLC Workflows
+
+aicgen injects a structured 6-command SDLC workflow into every generated assistant configuration. These commands guide the AI assistant through a repeatable, artifact-driven development lifecycle.
+
+## The Flow
+
+```
+/spec → /research → /plan → /build → /check → /ship
+```
+
+| Step | Command | Output artifact |
+|------|---------|----------------|
+| 1 | [`/spec [name]`](sdlc/spec.md) | `docs/specs/{name}.md` |
+| 2 | [`/research`](sdlc/research.md) | Appends `## Research Findings` to spec |
+| 3 | [`/plan`](sdlc/plan.md) | `docs/plans/{name}.md` |
+| 4 | [`/build [phase?]`](sdlc/build.md) | Code changes |
+| 5 | [`/check`](sdlc/check.md) | Inline verification report |
+| 6 | [`/ship`](sdlc/ship.md) | PR description draft |
+
+## Commands
+
+- [/spec](sdlc/spec.md) — Capture feature requirements before writing any code
+- [/research](sdlc/research.md) — Codebase scan + web research + infrastructure preference
+- [/plan](sdlc/plan.md) — Phased, checkpoint-driven implementation plan
+- [/build](sdlc/build.md) — Execute plan phase by phase with review checkpoints
+- [/check](sdlc/check.md) — Verify implementation against spec and run tests
+- [/ship](sdlc/ship.md) — Pre-flight checks and PR description draft
+
+## Output directory
+
+All spec and plan artifacts are saved to the `docs/` directory in the user's project. This directory is created automatically if it does not exist.
+
+```
+docs/
+├── specs/
+│   └── {feature-name}.md
+└── plans/
+    └── {feature-name}.md
+```
+
+## Guard rails
+
+| Command | Pre-condition |
+|---------|--------------|
+| `/research` | Active spec in `docs/specs/` — prompts `/spec` if missing |
+| `/plan` | Active spec with `## Research Findings` — warns if research was skipped |
+| `/build` | Active plan in `docs/plans/` — prompts `/plan` if missing |
+
+## Source
+
+Command definitions are maintained in [`aicgen/data/workflows/sdlc.md`](https://github.com/aicgen/aicgen/blob/main/data/workflows/sdlc.md) and injected into every generated config at `aicgen init` time.

package/data/workflows/sdlc/build.md

@@ -0,0 +1,38 @@
+# /build [phase]
+
+**Purpose:** Execute the next (or a specified) phase of the current implementation plan, pausing between phases for review.
+
+## When to use
+
+After `/plan`. Run once per phase until all phases are complete. Can also be used to re-execute a specific phase by passing its number.
+
+## Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `phase` | No | Phase number to execute. If omitted, executes the next incomplete phase. |
+
+## Pre-condition
+
+An active plan must exist in `docs/plans/`. If none is found, the assistant will prompt you to run `/plan` first and stop.
+
+## Steps
+
+1. Read the active plan from `docs/plans/`
+2. Determine the next incomplete phase (or the specified phase)
+3. Announce which phase is being executed and what it covers
+4. Implement step by step, following existing codebase patterns and conventions
+5. Summarise what was changed and created
+6. Mark the phase complete in the plan file
+7. Run relevant tests and report results
+8. Ask: "Phase {n} complete. Continue to phase {n+1}?" before proceeding
+
+## Behaviour
+
+- The assistant pauses after each phase and waits for your go-ahead
+- If tests fail at the end of a phase, the assistant reports failures before asking to continue
+- The plan file is updated in place as phases are completed — it acts as a progress tracker
+
+## Next step
+
+After all phases are complete, run [`/check`](check.md) to verify the full implementation against the spec.

package/data/workflows/sdlc/check.md

@@ -0,0 +1,46 @@
+# /check
+
+**Purpose:** Verify the current implementation against the active spec — tests, code review, and regression check.
+
+## When to use
+
+After `/build` phases are complete. Can also be run at any point during development to check progress. Safe to run repeatedly.
+
+## Steps
+
+1. Read the active spec from `docs/specs/` and plan from `docs/plans/`
+2. Run the full test suite and report results
+3. Review changed files against the spec's acceptance criteria — flag any gaps
+4. Check for regressions — unintended side effects in changed files
+5. Produce a structured report
+6. If all criteria are met and no regressions, prompt the user to run `/ship`
+
+## Output
+
+Inline structured report:
+
+```
+✅ Acceptance criteria met
+   - [criterion 1]
+   - [criterion 2]
+
+❌ Acceptance criteria not met
+   - [criterion] — [details of gap]
+
+⚠️  Potential regressions
+   - [file/behaviour] — [details]
+
+📋 Suggested fixes
+   - [fix 1]
+   - [fix 2]
+```
+
+## Tips
+
+- Run `/check` early and often — not just at the end
+- Use it after each `/build` phase to catch issues while context is fresh
+- A clean `/check` report is the gate for running `/ship`
+
+## Next step
+
+If all criteria are met and no regressions: run [`/ship`](ship.md).

package/data/workflows/sdlc/plan.md

@@ -0,0 +1,54 @@
+# /plan
+
+**Purpose:** Produce a phased, checkpoint-driven implementation plan based on the spec and research findings.
+
+## When to use
+
+After `/research`. This step breaks the work into independently verifiable phases that `/build` will execute one at a time.
+
+## Pre-condition
+
+An active spec with a `## Research Findings` section must exist in `docs/specs/`. If research was skipped, the assistant will warn you and ask for confirmation before proceeding.
+
+## Steps
+
+1. Read the active spec (including research findings) from `docs/specs/`
+2. Analyse the codebase — existing structure, patterns, conventions
+3. Break implementation into phases, each independently verifiable
+4. For each phase: list files to create or modify, key decisions, and verification steps
+5. Identify risks and propose mitigations
+6. Create `docs/plans/` if it does not exist
+7. Save the plan to `docs/plans/{spec-name}.md`
+8. Confirm saved and prompt the user to run `/build`
+
+## Output
+
+Creates `docs/plans/{spec-name}.md` with a phase-by-phase breakdown:
+
+```markdown
+# Plan: {name}
+
+## Overview
+{summary of approach}
+
+## Phase 1: {name}
+**Files:** {files to create or modify}
+**Steps:** {implementation steps}
+**Verify:** {how to confirm this phase is complete}
+
+## Phase 2: {name}
+...
+
+## Risks
+{risks and mitigations}
+```
+
+## Tips
+
+- Each phase should be completable in one focused work session
+- Verification steps should be concrete — runnable commands or observable outcomes
+- Order phases so each one builds on a stable foundation from the previous
+
+## Next step
+
+Run [`/build`](build.md) to execute the first phase of the plan.

package/data/workflows/sdlc/research.md

@@ -0,0 +1,60 @@
+# /research
+
+**Purpose:** Analyze the active spec with internal codebase scanning and external web research, and prompt for infrastructure preference before planning begins.
+
+## When to use
+
+After `/spec`, before `/plan`. This step surfaces codebase patterns, risks, and reference architectures that should inform the implementation plan.
+
+## Pre-condition
+
+An active spec must exist in `docs/specs/`. If none is found, the assistant will tell you to run `/spec` first and stop.
+
+## Steps
+
+1. Read the most recently modified spec from `docs/specs/`
+2. **Internal scan** — search codebase for related code, patterns, dependencies, conflicts
+3. **Infrastructure prompt** — ask the user:
+   > "Does this feature require infrastructure decisions?"
+   > - Cost-optimised / serverless (pay-per-use: Cloud Run, Cloud Functions, AWS Lambda, Fargate, etc.)
+   > - Fixed / dedicated (predictable load: Kubernetes, EC2, GKE, dedicated VMs, etc.)
+   > - No infrastructure involved
+4. **Web research** — search for architecture patterns, best practices, reference implementations, and cost comparisons relevant to the spec. Results are biased toward the chosen infrastructure model.
+5. Surface: recommended approaches, trade-offs, cost implications, reference links
+6. Suggest improvements or clarifications to the spec
+7. Append `## Research Findings` to the active spec file
+8. Prompt the user to run `/plan`
+
+## Infrastructure preference
+
+The infrastructure prompt shapes the direction of web research:
+
+| Choice | Research focus |
+|--------|---------------|
+| Serverless | Event-driven patterns, cold start mitigation, pay-per-use cost modelling, Cloud Run / Lambda / Fargate comparisons |
+| Fixed / dedicated | Kubernetes patterns, resource sizing, HA configuration, long-running process management |
+| No infrastructure | Pure code architecture, library selection, algorithm trade-offs |
+
+## Output
+
+Appends a `## Research Findings` section to the active spec file:
+
+```markdown
+## Research Findings
+
+### Internal codebase
+{relevant existing code, patterns, conflicts found}
+
+### Web research
+{architecture recommendations, reference links, cost comparisons}
+
+### Infrastructure recommendation
+{recommendation based on chosen preference}
+
+### Suggested spec improvements
+{clarifications or additions to the spec}
+```
+
+## Next step
+
+Run [`/plan`](plan.md) to turn the refined spec into a phased implementation plan.

package/data/workflows/sdlc/ship.md

@@ -0,0 +1,43 @@
+# /ship
+
+**Purpose:** Pre-flight wrap-up — verify everything is ready, then draft a PR description referencing the spec and plan.
+
+## When to use
+
+After `/check` reports all acceptance criteria met and no regressions. This is the final step of the SDLC workflow.
+
+## Steps
+
+1. Run the full test suite — stops and reports if any tests fail
+2. Read the active spec and plan
+3. Verify `docs/specs/{name}.md` and `docs/plans/{name}.md` are up to date
+4. List all uncommitted changes
+5. Draft a PR description:
+   ```
+   ## Summary
+   {goal from spec}
+
+   ## Changes
+   {summary of completed phases}
+
+   ## Spec
+   docs/specs/{name}.md
+
+   ## Plan
+   docs/plans/{name}.md
+
+   ## Test plan
+   {acceptance criteria as a checklist}
+   ```
+6. Present the PR description to the user for review
+7. Ask: "Ready to commit and push?" — if yes, stage all changes and create a conventional commit
+
+## Output
+
+A complete PR description ready to paste or submit. If the user confirms, a commit is created with a conventional commit message.
+
+## Tips
+
+- Do not run `/ship` if `/check` found unresolved issues
+- The PR description links to `docs/specs/` and `docs/plans/` — reviewers can follow the full decision trail
+- The commit message follows conventional commits format (e.g. `feat: add {feature-name}`)

package/data/workflows/sdlc/spec.md

@@ -0,0 +1,54 @@
+# /spec [name]
+
+**Purpose:** Capture the full specification for a feature or task before any code is written.
+
+## When to use
+
+Run this at the very start of any non-trivial feature or task. It ensures the AI assistant and developer share a common understanding of what is being built before any planning or implementation begins.
+
+## Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `name` | No | Feature name used as the filename. If omitted, the assistant will ask. |
+
+## Steps
+
+1. Ask for a feature name if not provided
+2. Gather: goal, user stories, acceptance criteria, constraints, and what is explicitly out of scope
+3. Create `docs/specs/` if it does not exist
+4. Save to `docs/specs/{name}.md`
+5. Confirm the file was saved and prompt the user to run `/research`
+
+## Output
+
+Creates `docs/specs/{name}.md` with this structure:
+
+```markdown
+# Spec: {name}
+
+## Goal
+{goal}
+
+## User Stories
+{user stories}
+
+## Acceptance Criteria
+{acceptance criteria}
+
+## Constraints
+{constraints}
+
+## Out of Scope
+{out of scope}
+```
+
+## Tips
+
+- Be specific in acceptance criteria — vague criteria lead to vague implementations
+- Out-of-scope is as important as in-scope; it prevents scope creep
+- The more detail here, the better `/research` and `/plan` will be
+
+## Next step
+
+Run [`/research`](research.md) to analyze the spec against the codebase and find reference solutions.

package/data/workflows/sdlc.md

@@ -0,0 +1,133 @@
+# SDLC Workflows
+
+## /spec [name]
+Capture the full specification for a feature or task before any code is written.
+
+**Steps:**
+1. Ask for a feature name if not provided as an argument
+2. Ask the user to describe: goal, user stories, acceptance criteria, constraints, and what is explicitly out of scope
+3. Create `docs/specs/` directory if it does not exist
+4. Save the gathered information to `docs/specs/{name}.md` using the template below
+5. Confirm the file was saved and prompt the user to run `/research`
+
+**Output template (`docs/specs/{name}.md`):**
+```markdown
+# Spec: {name}
+
+## Goal
+{goal}
+
+## User Stories
+{user stories}
+
+## Acceptance Criteria
+{acceptance criteria}
+
+## Constraints
+{constraints}
+
+## Out of Scope
+{out of scope}
+```
+
+---
+
+## /research
+Analyze the active spec with internal codebase scanning and external web research.
+
+**Pre-condition:** An active spec must exist in `docs/specs/` — if none is found, tell the user to run `/spec` first and stop.
+
+**Steps:**
+1. Read the most recently modified spec from `docs/specs/`
+2. **Internal scan:** Search the codebase for related code, existing patterns, similar implementations, dependencies, and potential conflicts relevant to the spec
+3. **Infrastructure prompt:** Ask the user:
+   > "Does this feature require infrastructure decisions?"
+   > - Cost-optimised / serverless (pay-per-use: Cloud Run, Cloud Functions, AWS Lambda, Fargate, etc.)
+   > - Fixed / dedicated (predictable load: Kubernetes, EC2, GKE, dedicated VMs, etc.)
+   > - No infrastructure involved
+4. **Web research:** Search for architecture patterns, best practices, reference implementations, and cost comparisons relevant to the spec. Bias results toward the chosen infrastructure model if one was selected.
+5. Surface: recommended approaches, trade-offs, cost implications, and links to reference material
+6. Suggest any improvements or clarifications to the spec based on findings
+7. Append a `## Research Findings` section to the active spec file containing: internal findings, web research summary, infrastructure recommendation (if applicable), and suggested spec improvements
+8. Prompt the user to run `/plan`
+
+---
+
+## /plan
+Produce a phased, checkpoint-driven implementation plan based on the spec and research findings.
+
+**Pre-condition:** An active spec with a `## Research Findings` section must exist — if research has not been run, warn the user and ask them to confirm they want to skip it before proceeding.
+
+**Steps:**
+1. Read the active spec (including research findings) from `docs/specs/`
+2. Analyse the codebase to understand existing structure, patterns, and conventions
+3. Break the implementation into phases — each phase must be independently verifiable
+4. For each phase, list: files to create or modify, key decisions, and how to verify it is complete
+5. Identify risks and propose mitigations
+6. Create `docs/plans/` directory if it does not exist
+7. Save the plan to `docs/plans/{spec-name}.md`
+8. Confirm the file was saved and prompt the user to run `/build`
+
+---
+
+## /build [phase]
+Execute the next (or a specified) phase of the current implementation plan.
+
+**Pre-condition:** An active plan must exist in `docs/plans/` — if none is found, tell the user to run `/plan` first and stop.
+
+**Steps:**
+1. Read the active plan from `docs/plans/`
+2. Determine the next incomplete phase (or the phase specified by the argument)
+3. Announce which phase is being executed and what it covers
+4. Implement the phase step by step, following existing codebase patterns and conventions
+5. After completing the phase, summarise what was changed and what was created
+6. Mark the phase as complete in the plan file
+7. Run any tests relevant to the completed phase and report results
+8. Pause and ask: "Phase {n} complete. Continue to phase {n+1}?" before proceeding
+
+---
+
+## /check
+Verify the current implementation against the active spec — tests, code review, and regression check.
+
+**Steps:**
+1. Read the active spec from `docs/specs/` and the active plan from `docs/plans/`
+2. Run the full test suite and report results
+3. Review all changed files against the spec's acceptance criteria — flag any gaps
+4. Check for regressions by reviewing changed files for unintended side effects
+5. Produce a structured report:
+   - ✅ Acceptance criteria met
+   - ❌ Acceptance criteria not met (with details)
+   - ⚠️ Potential regressions (with details)
+   - 📋 Suggested fixes
+6. If all criteria are met and no regressions are found, prompt the user to run `/ship`
+
+---
+
+## /ship
+Pre-flight wrap-up — verify everything is ready, then draft a PR description.
+
+**Steps:**
+1. Run the full test suite — stop and report if any tests fail
+2. Read the active spec and plan
+3. Verify that `docs/specs/{name}.md` and `docs/plans/{name}.md` are up to date
+4. Check for uncommitted changes and list them
+5. Draft a PR description referencing the spec and plan:
+   ```
+   ## Summary
+   {goal from spec}
+
+   ## Changes
+   {summary of phases completed}
+
+   ## Spec
+   docs/specs/{name}.md
+
+   ## Plan
+   docs/plans/{name}.md
+
+   ## Test plan
+   {acceptance criteria from spec as a checklist}
+   ```
+6. Present the PR description to the user for review
+7. Ask: "Ready to commit and push?" — if yes, stage all changes and create a commit with a conventional commit message