@rasensio/aidlc 0.4.0 → 0.7.0

package/skills/01-getting-started.md

@@ -1,131 +0,0 @@
----
-name: aidlc-getting-started
-description: Helps users get started with AIDLC — responds to onboarding questions, suggests templates, and guides first steps
-phase: ideation
-priority: 95
-trigger: When the user asks how to get started, how to use the framework, or asks about fixing bugs, adding features, or beginning work
----
-# Getting Started with AIDLC
-
-## Pre-condition: First Activation
-
-Before responding with this skill, check whether `.aidlc/context/` exists and contains at least one `.md` file. If it does NOT, defer to the **aidlc-first-activation** skill instead — it will scan the project, build context docs, and then hand control back to the user's original request. Do not proceed with getting-started guidance until first-activation has completed.
-
-## When to Activate
-
-Respond using this skill when the user asks any of the following:
-- "How do I get started?"
-- "How do I fix a bug?"
-- "How do I add a feature?"
-- "What should I do first?"
-- "How does this lifecycle thing work?"
-- "What template should I use?"
-- "Help me start working on X"
-
-## Quick Answers
-
-### "How do I fix a bug?"
-
-1. Start a bugfix lifecycle instance:
-   ```
-   aidlc start bugfix --name <short-description>
-   ```
-2. This creates a focused workflow: reproduce the bug → fix it → test it → deploy.
-3. Run `aidlc continue <name>` to see what step to do next.
-4. The bugfix template skips the design phase and requires a `reproduction.md` artifact first.
-
-### "How do I add a feature?"
-
-For a small, well-defined feature:
-```
-aidlc start quick-feature --name <feature-name>
-```
-
-For a larger feature needing design and review:
-```
-aidlc start full-feature --name <feature-name>
-```
-
-For something tiny (just code + test):
-```
-aidlc start micro-task --name <task-name>
-```
-
-### "How do I explore an idea or do research?"
-
-```
-aidlc start spike --name <research-topic>
-```
-This gives you Ideation + Requirements phases only — no implementation pressure.
-
-### "What should I do next?"
-
-Run:
-```
-aidlc continue
-```
-This tells you exactly which artifact to produce or which phase to enter next.
-
-### "How do I check progress?"
-
-```
-aidlc status
-```
-Shows all active lifecycle instances with completion %, current phase, and stall detection.
-
-### "How does the lifecycle work?"
-
-AIDLC guides your work through phases:
-
-1. **Ideation** — What are we building and why?
-2. **Requirements** — What are the acceptance criteria?
-3. **Design** — How will we build it?
-4. **Implementation** — Write the code
-5. **Testing** — Verify it works
-6. **Deployment** — Ship it
-7. **Maintenance** — Keep it running
-
-Not every task needs all phases. The templates handle this:
-- **micro-task** → Implementation + Testing only
-- **quick-feature** → Requirements through Deployment
-- **full-feature** → All 7 phases with review gates
-- **bugfix** → Requirements (reproduction) + Implementation + Testing + Deployment
-- **spike** → Ideation + Requirements (research) only
-
-### "How do I set up AIDLC in this project?"
-
-If AIDLC is already installed (you can see `.aidlc/skills/` in the project), just start using it:
-```
-aidlc start <template>
-```
-
-If not installed yet:
-```
-aidlc setup
-```
-This runs an interactive wizard that configures the framework for your project.
-
-## Choosing the Right Template
-
-| You want to... | Use this template | Scope |
-|---------------|-------------------|-------|
-| Fix a bug | `bugfix` | Standard (no design) |
-| Add a small feature | `quick-feature` | Standard |
-| Build something complex | `full-feature` | Full (with review gates) |
-| Just write code + test | `micro-task` | Micro |
-| Research / explore | `spike` | Ideation + Requirements |
-
-## After Starting
-
-Once you've started an instance, the framework tracks your progress. At any point:
-- `aidlc continue` — what to do next
-- `aidlc status` — overall progress
-- `aidlc gate <instance> <phase>` — check if a phase is complete
-- `aidlc transition <instance>` — advance to the next phase
-
-## State Location
-
-All lifecycle state lives in `.aidlc/state/<instance-name>/`. It's just YAML files — you can read them directly if needed. The key files are:
-- `instance.yaml` — which template, scope, and current phase
-- `phase-<name>.yaml` — artifact completion for each phase
-- `transitions.log` — history of phase transitions

package/skills/02-first-activation.md

@@ -1,158 +0,0 @@
----
-name: aidlc-first-activation
-description: Auto-discovers a brownfield project on first activation — scans codebase, asks about extra context folders, writes context docs
-phase: ideation
-priority: 98
-trigger: When AIDLC is installed but `.aidlc/context/` does not exist or contains no files
----
-# First Activation — Project Discovery
-
-## Purpose
-
-When AIDLC is freshly installed in an existing (brownfield) project, this skill runs once to build project context automatically. It replaces the need for the user to run `aidlc discover` from the terminal.
-
-## Activation Condition
-
-Activate this skill **before any other AIDLC skill** when ALL of the following are true:
-
-1. AIDLC skills are installed (`.aidlc/skills/` exists)
-2. The context directory is missing or empty (`.aidlc/context/` does not exist, or contains no `.md` files)
-3. The user has just sent a message (any message — they may be asking to fix a bug, add a feature, etc.)
-
-If `.aidlc/context/` already contains at least one `.md` file, skip this skill entirely and proceed with the user's request using the appropriate skill.
-
-## Behavior
-
-### Step 1: Acknowledge and Scan
-
-Tell the user briefly that you're indexing the project for the first time. Keep it short — don't block them with a wall of text.
-
-Example: *"First time here — let me scan the project quickly so I have context."*
-
-Then perform a lightweight scan:
-
-1. **Read manifest files** at the project root: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`, `Gemfile`, or equivalent.
-2. **List top-level directories** to understand the project structure.
-3. **Sample 3-5 source files** from the primary source directory to detect:
-   - Indentation style (tabs, 2-space, 4-space)
-   - Naming convention (camelCase, snake_case, PascalCase)
-   - Import style (grouped vs ungrouped)
-4. **Identify the tech stack**: language(s), frameworks, test runner, build tool, linter.
-
-### Step 2: Ask About Extra Context Folders
-
-After scanning, ask the user:
-
-> "I've got the basics — [summarize: language, framework, structure in one line].
->
-> Beyond the source code, are there any folders I should be aware of for ongoing context? For example: specs, roadmap, architecture decisions, API schemas, design docs, etc."
-
-Wait for the user's answer. Common examples:
-- `specs/`, `docs/`, `roadmap/`, `architecture/`, `adr/`, `design/`, `api/`
-- The user might also point to specific files like `ARCHITECTURE.md` or `openapi.yaml`
-
-If the user says "no" or "that's it," proceed without extra folders.
-
-### Step 3: Read Extra Context
-
-For each folder or file the user mentions:
-1. List its contents (non-recursive, top level only for folders)
-2. Read key files (prefer: index files, READMEs, YAML/JSON schemas, markdown docs)
-3. Summarize what you found — don't copy entire documents verbatim
-
-Cap this step: read at most 10 files total from extra context folders. If there's more, note what was skipped and tell the user they can point you at specific files later.
-
-### Step 4: Write Context Documents
-
-Create `.aidlc/context/` and write:
-
-#### `style-guide.md`
-```markdown
----
-generated_by: aidlc-first-activation
-generated_at: <ISO 8601 UTC>
----
-# Style Guide
-
-## Languages
-<table of languages with approximate file counts>
-
-## Conventions
-- Indentation: <detected>
-- Naming: <detected>
-- Import style: <detected>
-
-## Frameworks & Tools
-<list of detected frameworks, test runners, build tools>
-```
-
-#### `architecture.md`
-```markdown
----
-generated_by: aidlc-first-activation
-generated_at: <ISO 8601 UTC>
----
-# Architecture Overview
-
-## Tech Stack
-<primary languages and frameworks>
-
-## Directory Structure
-<role mapping of top-level directories>
-
-## Entry Points
-<detected entry points>
-
-## Configuration
-<config approach: env vars, YAML, etc.>
-```
-
-#### `project-knowledge.md` (only if the user provided extra folders)
-```markdown
----
-generated_by: aidlc-first-activation
-generated_at: <ISO 8601 UTC>
-source_paths:
-  - <path1>
-  - <path2>
----
-# Project Knowledge
-
-## Sources
-<list of folders/files the user pointed to>
-
-## Summary
-
-### <Folder/File 1 Name>
-<2-5 sentence summary of what's in there and what's relevant>
-
-### <Folder/File 2 Name>
-<2-5 sentence summary>
-
-## Key References
-<specific files worth reading in full when working on related areas>
-```
-
-### Step 5: Confirm and Continue
-
-After writing the context docs, briefly confirm:
-
-> "Done — indexed the project. Context saved to `.aidlc/context/`. Now, back to your request..."
-
-Then **immediately proceed** with whatever the user originally asked. Do not make them repeat themselves. Their original message is still the active task — discovery was a transparent preamble.
-
-## Important Notes
-
-- **This skill runs exactly once per project.** After context docs are written, it never triggers again.
-- **Don't over-scan.** This is a lightweight pass, not a full AST analysis. 3-5 sampled files is enough for style detection.
-- **Don't block the user.** The scan should feel like a 10-second preamble, not a separate workflow. If the project is huge, just scan what you can quickly and note gaps.
-- **Respect .gitignore patterns.** Don't scan `node_modules/`, `dist/`, `build/`, `.git/`, etc.
-- **Extra context is optional.** If the user says "nah, just the code" — that's fine. Skip `project-knowledge.md`.
-- **The user's original request takes priority.** Discovery enables better answers but must not derail the conversation.
-
-## Exit Criteria
-
-- `.aidlc/context/style-guide.md` exists with detected conventions
-- `.aidlc/context/architecture.md` exists with structure overview
-- `.aidlc/context/project-knowledge.md` exists (if extra folders were provided)
-- The user's original request is being addressed (not abandoned)

package/skills/10-ideation.md

@@ -1,45 +0,0 @@
----
-name: aidlc-ideation
-description: Guides the Ideation phase — exploring the problem space, defining goals and constraints
-phase: ideation
-priority: 50
----
-# Ideation Phase
-
-## Purpose
-
-Explore the problem space before committing to a solution. Define what we are building, why, and what constraints exist.
-
-## Entry Criteria
-
-- A lifecycle instance has been created with a Full scope
-- The instance is claimed by this session
-
-## Required Artifacts
-
-- `ideation.md` — Problem statement, goals, constraints, initial ideas, and open questions
-
-## Instructions
-
-1. **Clarify the problem.** Ask the user what they want to build and why. Identify the core need vs. nice-to-haves.
-2. **Explore constraints.** Document: timeline, technical constraints, platform limitations, team size, budget considerations.
-3. **Generate options.** Propose 2-3 approaches. For each, note trade-offs (complexity, time, risk).
-4. **Identify unknowns.** List open questions that need answers before requirements can be written.
-5. **Summarize.** Write `ideation.md` with sections: Problem Statement, Goals, Constraints, Explored Options, Open Questions.
-
-## Exit Criteria
-
-- `ideation.md` exists and contains at minimum a problem statement and one defined goal
-- The user has confirmed the direction (which option to pursue or a synthesis)
-
-## Guidance
-
-{{guidance:secure-defaults}}
-
-## Security Confirmation
-
-If any ideation option involves sensitive operations (new credentials, infrastructure provisioning, access control changes), flag it explicitly and note that confirmation will be required before execution in later phases.
-
-## Completion
-
-When exit criteria are met, update `phase-ideation.yaml` status to `complete` and append a transition record to `transitions.log`.

package/skills/20-requirements.md

@@ -1,54 +0,0 @@
----
-name: aidlc-requirements
-description: Guides the Requirements phase — defining acceptance criteria and user stories
-phase: requirements
-priority: 50
----
-# Requirements Phase
-
-## Purpose
-
-Translate the ideation output (or the user's direct request) into precise, testable acceptance criteria.
-
-## Entry Criteria
-
-- Ideation phase complete (Full scope) OR instance created with Standard scope
-- The instance is claimed by this session
-
-## Required Artifacts
-
-- `requirements.md` — User stories, acceptance criteria, scope boundaries, non-functional requirements
-
-## Instructions
-
-1. **Gather requirements.** If a Full scope, read `ideation.md` for context. Otherwise, ask the user to describe desired behavior.
-2. **Write user stories.** Use the format: "As a [role], I want [capability], so that [benefit]."
-3. **Define acceptance criteria.** Each criterion must be:
-   - Specific and unambiguous
-   - Testable (an observable outcome)
-   - Independent (not relying on unstated assumptions)
-4. **Set scope boundaries.** Explicitly state what is NOT included.
-5. **Non-functional requirements.** Address performance, security, accessibility, and compatibility where relevant.
-6. **For complex input**: If requirements are extensive, create an Input_File at `.aidlc/inbox/requirements-input.md` with structured sections for the user to fill in, rather than asking many sequential questions.
-
-## Exit Criteria
-
-- `requirements.md` exists with at least one user story and corresponding acceptance criteria
-- Each acceptance criterion is testable (has an observable pass/fail condition)
-- The user has confirmed the requirements are complete for the chosen scope
-
-## Guidance
-
-{{context:style-guide}}
-{{guidance:secure-defaults}}
-
-## Security Confirmation
-
-If requirements reference sensitive data handling, authentication flows, or access control:
-1. Explicitly document the security requirements as acceptance criteria
-2. Flag that a security review will be needed before deployment
-3. Never embed credentials or secrets in requirement examples
-
-## Completion
-
-When exit criteria are met, update `phase-requirements.yaml` status to `complete` and append a transition record to `transitions.log`.

package/skills/30-design.md

@@ -1,57 +0,0 @@
----
-name: aidlc-design
-description: Guides the Design phase — architecture decisions, interfaces, and data flow
-phase: design
-priority: 50
----
-# Design Phase
-
-## Purpose
-
-Produce a technical design that satisfies the requirements. Define architecture, interfaces, data models, and integration points before writing code.
-
-## Entry Criteria
-
-- Requirements phase complete
-- The instance is claimed by this session
-
-## Required Artifacts
-
-- `design.md` — Architecture overview, component design, interfaces, data flow, and design decisions with rationale
-
-## Instructions
-
-1. **Review requirements.** Read `requirements.md` (or its summary if one exists). Identify the key technical challenges.
-2. **Define architecture.** Describe the high-level structure: components, their responsibilities, and how they communicate.
-3. **Specify interfaces.** For each component boundary, define the contract (function signatures, API shapes, data types).
-4. **Data flow.** Document how data moves through the system — inputs, transformations, storage, outputs.
-5. **Design decisions.** Record each significant decision with rationale and alternatives considered.
-6. **Address non-functional concerns.** Map performance, security, and accessibility requirements to design choices.
-7. **Identify risks.** Note technical risks and mitigation strategies.
-
-## Exit Criteria
-
-- `design.md` exists with architecture, interfaces, and at least one design decision with rationale
-- The design addresses all acceptance criteria from `requirements.md`
-- The user has confirmed the design direction
-
-## Guidance
-
-{{context:architecture}}
-{{context:style-guide}}
-{{guidance:secure-defaults}}
-{{guidance:accessibility}}
-
-## Security Confirmation
-
-If the design involves:
-- New authentication or authorization flows
-- Data storage of sensitive information
-- External service integrations with credentials
-- Infrastructure provisioning
-
-You MUST flag these explicitly in the design document and note that implementation will require security confirmation before proceeding.
-
-## Completion
-
-When exit criteria are met, update `phase-design.yaml` status to `complete` and append a transition record to `transitions.log`.

package/skills/40-implementation.md

@@ -1,64 +0,0 @@
----
-name: aidlc-implementation
-description: Guides the Implementation phase — writing code following the design and project conventions
-phase: implementation
-priority: 50
----
-# Implementation Phase
-
-## Purpose
-
-Produce working code that satisfies the design and requirements. Follow project conventions discovered in context docs.
-
-## Entry Criteria
-
-- Design phase complete (Full/Standard scope) OR instance created with Micro scope (task description + criteria exist)
-- The instance is claimed by this session
-
-## Required Artifacts
-
-- Source code changes implementing the feature or fix
-- Updated or new tests (handed off to Testing phase for verification)
-
-## Instructions
-
-1. **Load context.** Read `.aidlc/context/style-guide.md` and `.aidlc/context/architecture.md` if they exist. Match the project's established patterns.
-2. **Load guidance.** Read all active Guidance_Layers from `.aidlc/guidance/index.yaml`. Apply their rules during implementation.
-3. **Plan the work.** Break the implementation into discrete steps. For Micro scope, reference the task description and acceptance criteria directly.
-4. **Write code.** Follow the design interfaces. Match existing code style (naming, formatting, error handling patterns).
-5. **Handle sensitive operations.** Before executing any of the following, describe the action and wait for explicit user confirmation:
-   - File deletions or destructive operations
-   - Infrastructure changes (provisioning, configuration)
-   - Permission or access control modifications
-   - Credential or secret handling
-6. **Commit incrementally.** Produce working code at each step; avoid large uncommittable diffs.
-7. **Update state.** As implementation artifacts are produced, mark them in `phase-implementation.yaml`.
-
-## Exit Criteria
-
-- All acceptance criteria from requirements are addressed in code
-- Code follows project style (naming, formatting, patterns from context docs)
-- No unresolved TODOs or placeholder implementations remain for required functionality
-- Guidance layer rules have been applied (security defaults, accessibility, API conventions)
-
-## Guidance
-
-{{context:style-guide}}
-{{context:architecture}}
-{{guidance:secure-defaults}}
-{{guidance:accessibility}}
-{{guidance:api-conventions}}
-
-## Security Confirmation
-
-Before proceeding with any sensitive operation during implementation:
-1. Describe what the operation does and what it affects
-2. State whether it is reversible
-3. Wait for explicit user acknowledgment
-4. If the user cancels, halt execution and log the cancellation with a timestamp in state
-
-Never store credentials, API keys, tokens, or passwords in source code or state files. Use placeholder syntax for secrets (e.g., `${SECRET_NAME}`).
-
-## Completion
-
-When exit criteria are met, update `phase-implementation.yaml` status to `complete` and append a transition record to `transitions.log`.

package/skills/50-testing.md

@@ -1,60 +0,0 @@
----
-name: aidlc-testing
-description: Guides the Testing phase — verifying implementation against requirements
-phase: testing
-priority: 50
----
-# Testing Phase
-
-## Purpose
-
-Verify that the implementation satisfies all acceptance criteria. Produce evidence of correctness through automated tests and manual verification where needed.
-
-## Entry Criteria
-
-- Implementation phase complete
-- The instance is claimed by this session
-
-## Required Artifacts
-
-- Test files covering acceptance criteria
-- `testing.md` — Test plan, results summary, and coverage notes
-
-## Instructions
-
-1. **Review acceptance criteria.** Read `requirements.md` (or task description for Micro scope). Each criterion needs at least one test.
-2. **Write automated tests.** Follow the project's existing test patterns:
-   - Unit tests for pure logic and edge cases
-   - Integration tests for component interactions
-   - Property-based tests where inputs have broad domains
-3. **Run tests.** Execute the project's test suite. All new tests must pass.
-4. **Document results.** Write `testing.md` with:
-   - Test plan (what was tested and why)
-   - Results (pass/fail counts, any notable findings)
-   - Coverage notes (which criteria are covered, any gaps)
-5. **Address failures.** If tests reveal bugs, fix the implementation. Do not skip or weaken tests to force a pass.
-
-## Exit Criteria
-
-- All acceptance criteria have corresponding test coverage
-- All tests pass
-- `testing.md` exists with results summary
-- No critical bugs remain open
-
-## Guidance
-
-{{context:style-guide}}
-{{guidance:secure-defaults}}
-
-## Security Confirmation
-
-If testing requires:
-- Access to production-like environments
-- Use of real credentials or sensitive data
-- Execution of destructive operations (even in test environments)
-
-You MUST describe the action, confirm it targets a safe environment, and wait for user acknowledgment before proceeding.
-
-## Completion
-
-When exit criteria are met, update `phase-testing.yaml` status to `complete` and append a transition record to `transitions.log`.

package/skills/60-deployment.md

@@ -1,63 +0,0 @@
----
-name: aidlc-deployment
-description: Guides the Deployment phase — release preparation, validation, and execution
-phase: deployment
-priority: 50
----
-# Deployment Phase
-
-## Purpose
-
-Prepare and execute the release. Ensure all preceding phases are complete, all gates pass, and the deployment itself is safe and reversible.
-
-## Entry Criteria
-
-- All preceding required phases have status `complete` in the State_Store
-- Testing phase complete with all tests passing
-- Security sign-off recorded (if a security review phase is configured)
-- The instance is claimed by this session
-
-## Required Artifacts
-
-- `deployment.md` — Release plan, rollback strategy, deployment checklist
-
-## Instructions
-
-1. **Validate readiness.** Run `aidlc gate deployment` (or check state manually): every preceding required phase must be complete. If any gate fails, address the gap before proceeding.
-2. **Write release plan.** Document in `deployment.md`:
-   - What is being deployed (version, changes summary)
-   - Target environment(s)
-   - Deployment steps in order
-   - Rollback procedure
-   - Monitoring and verification steps post-deploy
-3. **Pre-deployment checks.** Verify:
-   - CI pipeline passes
-   - No critical findings open from adversarial reviews
-   - Dependencies are pinned and audited
-4. **Execute deployment.** Follow the release plan step by step.
-5. **Verify.** Confirm the deployment succeeded using the monitoring steps.
-
-## Exit Criteria
-
-- `deployment.md` exists with release plan and rollback strategy
-- Deployment executed successfully (or plan approved for manual execution)
-- Post-deployment verification confirms expected behavior
-
-## Security Confirmation
-
-Deployment is inherently sensitive. You MUST:
-1. Confirm the target environment with the user (production vs. staging vs. dev)
-2. Present the full list of changes being deployed
-3. Confirm rollback procedure exists and is tested
-4. Wait for explicit user approval before executing any deployment command
-5. If deploying to production, require additional confirmation stating the environment name
-
-Never deploy without explicit user confirmation. If the user cancels, halt and log the cancellation.
-
-## Guidance
-
-{{guidance:secure-defaults}}
-
-## Completion
-
-When exit criteria are met, update `phase-deployment.yaml` status to `complete` and append a transition record to `transitions.log`.

package/skills/70-maintenance.md

@@ -1,56 +0,0 @@
----
-name: aidlc-maintenance
-description: Guides the Maintenance phase — monitoring, iteration, and documentation upkeep
-phase: maintenance
-priority: 50
----
-# Maintenance Phase
-
-## Purpose
-
-Ensure the deployed feature remains healthy. Update documentation, address feedback, and plan follow-up work.
-
-## Entry Criteria
-
-- Deployment phase complete
-- The instance is claimed by this session
-
-## Required Artifacts
-
-- `maintenance.md` — Post-deployment notes, monitoring status, known issues, follow-up items
-
-## Instructions
-
-1. **Monitor.** Check that the deployed changes behave as expected in their target environment. Note any anomalies.
-2. **Update documentation.** Ensure project docs reflect the new state:
-   - README or user-facing docs updated if behavior changed
-   - Architecture docs updated if new components were added
-   - API docs updated if endpoints changed
-3. **Gather feedback.** Collect user/team feedback on the delivered feature.
-4. **Record known issues.** Document any edge cases, limitations, or technical debt introduced.
-5. **Plan follow-up.** If feedback or monitoring reveals needed improvements, document them as potential future lifecycle instances.
-6. **Close the instance.** When maintenance tasks are complete, mark the lifecycle instance as done.
-
-## Exit Criteria
-
-- `maintenance.md` exists with post-deployment status
-- Documentation is updated to reflect the delivered changes
-- No critical issues remain unaddressed
-- Follow-up items are documented (even if deferred to new instances)
-
-## Security Confirmation
-
-If maintenance involves:
-- Modifying production configuration
-- Rotating credentials or updating access controls
-- Patching security vulnerabilities
-
-You MUST describe the change, confirm the target environment, and wait for explicit user approval before proceeding.
-
-## Guidance
-
-{{guidance:secure-defaults}}
-
-## Completion
-
-When exit criteria are met, update `phase-maintenance.yaml` status to `complete`, append a transition record to `transitions.log`, and fire the `on-instance-complete` event.