Skip to content

skill · phase: ideation

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

{{glossary:template}}

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"

How Work Begins

All lifecycle work runs on instances — YAML state under .aidlc/state/<name>/. You (the agent) create and manage them directly by following the state protocol in aidlc-overview; no terminal command is needed. The aidlc CLI remains an equivalent shortcut for users who prefer it (aidlc start <template> --name <name>).

Quick Answers

"How do I fix a bug?"

{{glossary:instance}}

  1. Create a lifecycle instance from the bugfix template (see "Creating an Instance" in aidlc-overview).
  2. This gives a focused workflow: reproduce the bug → fix it → test it → deploy. The bugfix template skips the design phase and requires a reproduction.md artifact first.
  3. Follow aidlc-continue at any point to pick up the next step.

"How do I add a feature?"

Create an instance from the template that fits:

  • Small, well-defined feature → quick-feature
  • Larger feature needing design and review → full-feature
  • Something tiny (just code + test) → micro-task

"This is a chore I do over and over — does it need an instance?"

No. The rule is: lifecycle for changes to the system; skills for repeatable operations of the system. Publishing a post, rotating a log, regenerating a report — the system already supports these, so they belong in a skill rather than a lifecycle instance. See "Lifecycle or Skill?" in aidlc-overview for the rule, the escape hatch when an operation reveals a missing capability, and a worked example.

Run aidlc add skill <name> to scaffold one with verification steps already built in. If you would rather author the skill through the lifecycle, use the micro-task template — the deliverable is the skill file plus its check.

"How do I explore an idea or do research?"

Create an instance from the spike template. This gives you Ideation + Requirements phases only — no implementation pressure.

"What should I do next?"

Follow the aidlc-continue skill: it reads the instance state and identifies exactly which artifact to produce or which phase to enter next. (CLI shortcut: aidlc continue.)

"How do I check progress?"

Read each instance's instance.yaml and phase-<name>.yaml files and summarize: current phase, completion percentage (complete artifacts ÷ required artifacts), and stalled instances. (CLI shortcut: aidlc status.)

"How is the project doing overall?"

Run aidlc metrics (add --json for machine-readable output): change failure rate per template, lead time per phase and instance, which features caused bugfixes (caused_by linkage), and true cost — an instance's own cost plus the bugfixes it caused. Values without data show as "no data"/"unknown", never fabricated zeros.

"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: create an instance and begin.

If not installed yet, run npx @rasensio/aidlc init in a terminal. Installation is the one step that genuinely needs the CLI — it compiles the skills into your platform's native format and configures the project.

Choosing the Right Template

{{glossary:scope}}

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
Author an operational skill micro-task Micro (or just aidlc add skill)

Template definitions (phases and required artifacts) live in the content package and can be overridden per-project under .aidlc/templates/.

After Starting

Once an instance exists, the state files track your progress. At any point:

  • aidlc-continue skill — determine and execute the next step
  • Read state files — overall progress (see "How do I check progress?")
  • Gate check — a phase is complete when all its required artifacts are complete; aidlc gate <phase> provides the same check for CI
  • Transition — advance current_phase and append to transitions.log per the state protocol

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