@rasensio/aidlc 0.1.0

package/skills/20-requirements.md

@@ -0,0 +1,54 @@
+---
+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

@@ -0,0 +1,57 @@
+---
+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

@@ -0,0 +1,64 @@
+---
+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

@@ -0,0 +1,60 @@
+---
+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

@@ -0,0 +1,63 @@
+---
+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

@@ -0,0 +1,56 @@
+---
+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.

package/skills/80-review.md

@@ -0,0 +1,85 @@
+---
+name: aidlc-review
+description: Performs adversarial review of lifecycle artifacts — examining for ambiguities, gaps, and risks
+phase: requirements
+trigger: Activated when a review is requested for any artifact or phase
+priority: 60
+---
+# Adversarial Review
+
+## Purpose
+
+Provide a structured, critical review of a lifecycle artifact from fresh context. Surface ambiguities, contradictions, missing edge cases, and risks before the artifact drives downstream work.
+
+## Important
+
+You MUST perform this review with fresh eyes. If you authored the artifact being reviewed, delegate to a separate session or subagent. Self-review defeats the purpose.
+
+## Entry Criteria
+
+- A target artifact exists (requirements.md, design.md, or other phase artifact)
+- The reviewer is a different session/agent than the artifact author
+
+## Required Artifacts
+
+- `<artifact>.review.md` — Structured findings file in the instance namespace
+
+## Instructions
+
+1. **Read the target artifact completely.** Do not skim.
+2. **Examine for each dimension:**
+   - **Ambiguities** — Vague terms, undefined behavior, unclear scope
+   - **Contradictions** — Requirements that conflict with each other
+   - **Missing edge cases** — Inputs, states, or scenarios not addressed
+   - **Untestable criteria** — Requirements with no observable pass/fail
+   - **Hidden assumptions** — Unstated preconditions the artifact relies on
+   - **Security gaps** — Missing auth, unvalidated input, exposed data
+   - **Scalability concerns** — Performance bottlenecks or resource limits
+   - **Scope creep** — Functionality beyond the stated scope
+3. **Write findings.** For each issue found, record:
+   - **Severity**: `critical`, `major`, or `minor`
+   - **Section**: The specific part of the artifact
+   - **Issue**: Clear description of the problem
+   - **Suggestion**: A concrete resolution or question to ask
+   - **Status**: `open` (always for new findings)
+4. **Save the findings file** as `<artifact>.review.md` in the instance namespace.
+
+## Findings Format
+
+```markdown
+---
+artifact: <filename>
+reviewed_at: <ISO 8601 UTC>
+reviewer: <session-id>
+---
+
+## Finding 1
+- **Severity:** critical | major | minor
+- **Section:** <section reference>
+- **Issue:** <description>
+- **Suggestion:** <resolution>
+- **Status:** open
+```
+
+## Exit Criteria
+
+- Findings file exists in the instance namespace
+- Every dimension was considered (even if no issues found — state "no issues" for that dimension)
+- Findings are actionable (each has a concrete suggestion or question)
+
+## Review Gate
+
+When a Workflow_Template configures an adversarial review gate for a phase, the phase transition is blocked until:
+- A findings file exists for the phase's required artifacts
+- No finding with severity `critical` has status `open`
+
+## Security Confirmation
+
+If the review identifies security vulnerabilities:
+1. Flag them as `critical` severity
+2. Note that these MUST be resolved before deployment
+3. If the vulnerability involves exposed credentials or active exploits, alert the user immediately rather than only recording a finding
+
+## Completion
+
+After writing the findings file, report the review summary: total findings count by severity, and whether any critical findings block phase transition.

package/skills/81-continue.md

@@ -0,0 +1,57 @@
+---
+name: aidlc-continue
+description: Resumes a lifecycle instance from the next incomplete step with minimal context loading
+phase: implementation
+priority: 70
+---
+# Lifecycle Continuation
+
+## Purpose
+
+Resume an in-progress lifecycle instance efficiently. Determine where work left off and continue from that exact point without re-reading full artifacts or re-explaining context.
+
+## Instructions
+
+1. **Load state.** Read `.aidlc/state/<instance>/instance.yaml` to get:
+   - Current phase
+   - Template name
+   - Scope
+   - Claim status
+2. **Check claim.** If another session holds the claim:
+   - Check `renewed_at` against the staleness timeout (default: 60 minutes)
+   - If stale: warn and request override confirmation before taking over
+   - If active: warn and do NOT proceed without explicit override
+3. **Claim the instance.** Record your session identifier and timestamp in the claim fields.
+4. **Determine next step.** Apply this priority:
+   - If current phase has incomplete required artifacts → produce the next artifact
+   - If current phase is complete but not transitioned → evaluate transition (check gates)
+   - If transition is allowed → move to next pending phase
+   - If all phases complete → report instance complete and fire `on-instance-complete`
+5. **Load minimal context.** Read only:
+   - The skill for the determined phase
+   - Artifact summaries (`.summary.md`) instead of full artifacts where available
+   - Compact state files, not full transition history
+6. **Execute.** Follow the phase skill for the determined step.
+
+## Multiple Instances
+
+When multiple instances are active and the user did not specify which one:
+- List all active instances: name, current phase, completion percentage
+- Ask the user to select one
+- Resume the selected instance
+
+## Exit Criteria
+
+- The next step is identified and executed (or the instance is reported as complete)
+- State is updated to reflect progress
+- Claim is held for the duration of work
+
+## Security Confirmation
+
+If continuation leads to a phase that involves sensitive operations (Deployment, infrastructure changes), apply the security confirmation rules of that phase's skill before executing.
+
+## Token Efficiency
+
+- Do NOT re-read unchanged files from prior sessions
+- Use state fields to determine progress, not artifact content
+- Load Artifact_Summaries in place of full documents when summaries exist

package/skills/82-add-action.md

@@ -0,0 +1,71 @@
+---
+name: aidlc-add-action
+description: Translates natural language automation descriptions into Lifecycle_Action declarations
+phase: implementation
+priority: 55
+---
+# AI-Assisted Action Authoring
+
+## Purpose
+
+Help the user create Lifecycle_Actions from natural language descriptions. Translate intent into a concrete, validated `.aidlc/actions.yaml` entry.
+
+## Instructions
+
+1. **Receive the description.** The user provides a natural language description of the automation they want (e.g., "create a log file every time we finish a feature").
+
+2. **Infer the lifecycle event.** Map the described trigger to one of:
+   - `on-instance-start` — when a lifecycle instance is created
+   - `on-phase-enter` — when entering a specific phase
+   - `on-phase-exit` — when exiting a specific phase
+   - `on-instance-complete` — when all phases are done
+   - `on-artifact-created` — when a lifecycle artifact is produced
+
+   If the trigger cannot be mapped, list all available events and ask the user to select one.
+
+3. **Compose the action declaration.** Determine:
+   - **event**: The lifecycle event from step 2
+   - **phase_filter** (optional): Which phase(s) this applies to
+   - **action**: A built-in action name (`git-branch`, `github-issue`, `doc-update`) or a custom shell command
+   - **blocking**: `true` if the transition should halt on failure, `false` otherwise
+   - **description**: Preserve the user's original natural language intent
+
+4. **Present for confirmation.** Show the user:
+   ```yaml
+   - event: <event>
+     action: <command or built-in>
+     blocking: <true|false>
+     description: "<original intent>"
+   ```
+   Ask: "Does this look correct? Confirm to save, or describe changes."
+
+5. **Validate.** Before saving, validate the entry against the actions.yaml schema.
+
+6. **Save.** On confirmation + valid schema, append the entry to `.aidlc/actions.yaml`.
+
+7. **Offer dry-run.** After saving, offer to test-fire the action with a sample event payload (no real transition occurs).
+
+## Security Confirmation
+
+If the generated command references sensitive operations:
+- File deletion (`rm`, `del`)
+- Infrastructure changes (`terraform`, `aws`, `kubectl`)
+- Permission modifications (`chmod`, `chown`, IAM changes)
+
+You MUST:
+1. Warn the user that this action will execute automatically on the lifecycle event
+2. Explain what the command does and what it affects
+3. Require explicit confirmation that the user accepts the automated execution
+4. If declined, do NOT save the entry — `actions.yaml` remains untouched
+
+## Error Handling
+
+- If the user declines confirmation: do not write anything, report that the action was not saved
+- If schema validation fails: display the violation, do not save, suggest corrections
+- If the description is too ambiguous to infer an event: list events and prompt selection
+
+## Exit Criteria
+
+- Action entry saved to `.aidlc/actions.yaml` (on confirmation) OR
+- User explicitly declined (no file changes made)
+- Dry-run offered after successful save

package/templates/bugfix.yaml

@@ -0,0 +1,14 @@
+name: bugfix
+description: Bug fix workflow with reproduction steps, no design phase.
+extends: quick-feature
+scope: standard
+phases: []
+remove:
+  - design
+override:
+  requirements:
+    required_artifacts:
+      - name: reproduction.md
+      - name: requirements.md
+gates:
+  adversarial-review: []

package/templates/full-feature.yaml

@@ -0,0 +1,44 @@
+name: full-feature
+description: Full lifecycle from ideation through maintenance with adversarial review gates.
+extends: null
+scope: full
+phases:
+  - name: ideation
+    required_artifacts:
+      - name: idea.md
+    optional_artifacts:
+      - name: research-notes.md
+  - name: requirements
+    required_artifacts:
+      - name: requirements.md
+    optional_artifacts:
+      - name: stakeholder-notes.md
+  - name: design
+    required_artifacts:
+      - name: design.md
+    optional_artifacts:
+      - name: architecture-diagram.md
+  - name: implementation
+    required_artifacts:
+      - name: code-complete.md
+    optional_artifacts:
+      - name: implementation-notes.md
+  - name: testing
+    required_artifacts:
+      - name: test-results.md
+    optional_artifacts:
+      - name: coverage-report.md
+  - name: deployment
+    required_artifacts:
+      - name: deployment-record.md
+    optional_artifacts:
+      - name: rollback-plan.md
+  - name: maintenance
+    required_artifacts:
+      - name: maintenance-plan.md
+    optional_artifacts:
+      - name: monitoring-config.md
+gates:
+  adversarial-review:
+    - requirements
+    - design

package/templates/micro-task.yaml

@@ -0,0 +1,11 @@
+name: micro-task
+description: Minimal workflow for small tasks requiring only implementation and testing.
+extends: null
+scope: micro
+phases:
+  - name: implementation
+    required_artifacts:
+      - name: code-complete.md
+  - name: testing
+    required_artifacts:
+      - name: test-results.md

package/templates/quick-feature.yaml

@@ -0,0 +1,20 @@
+name: quick-feature
+description: Standard feature workflow from requirements through deployment.
+extends: null
+scope: standard
+phases:
+  - name: requirements
+    required_artifacts:
+      - name: requirements.md
+  - name: design
+    required_artifacts:
+      - name: design.md
+  - name: implementation
+    required_artifacts:
+      - name: code-complete.md
+  - name: testing
+    required_artifacts:
+      - name: test-results.md
+  - name: deployment
+    required_artifacts:
+      - name: deployment-record.md

package/templates/spike.yaml

@@ -0,0 +1,15 @@
+name: spike
+description: Spike or research workflow for exploration and findings documentation.
+extends: null
+scope: standard
+phases:
+  - name: ideation
+    required_artifacts:
+      - name: research-question.md
+    optional_artifacts:
+      - name: prior-art.md
+  - name: requirements
+    required_artifacts:
+      - name: findings.md
+    optional_artifacts:
+      - name: recommendations.md