@rasensio/aidlc-content 1.8.1 → 1.9.1

package/guidance/content-operations.md

@@ -0,0 +1,71 @@
+---
+name: content-operations
+description: Verification steps for the output of repeatable operational skills
+---
+# Content Operations
+
+Verification steps for operational skills — skills that perform a repeatable
+operation on a system rather than change the system itself.
+
+This file is **not** registered in `index.yaml` and is not a project guidance
+layer. It is a source read directly from the content package by
+`aidlc add skill`, which copies the delimited region below verbatim into every
+generated skill body. Two consequences for anyone editing it:
+
+- **Do not use `{{...}}` placeholder syntax anywhere in this file.** The text is
+  inlined literally, so a placeholder would ship unresolved to users.
+- Edits reach existing skills only when they are re-emitted
+  (`aidlc add skill --re-emit`). Generated skills are snapshots, pinned by the
+  `content_version` field in their frontmatter.
+
+<!-- aidlc:verify-steps:begin -->
+## Verification
+
+Before reporting this operation as complete, work through every check below.
+Report which ones you ran and what they returned. If a check does not apply,
+say so explicitly rather than skipping it silently.
+
+### 1. Factual review of generated claims
+
+- Re-read anything you asserted as fact — names, dates, versions, numbers,
+  behaviour of other systems. Confirm each against a source you actually
+  consulted in this session, not against recollection.
+- Where a claim could not be verified, mark it as unverified in the output
+  rather than leaving it to read as established fact.
+- Check that quoted or paraphrased material still means what the source meant.
+
+### 2. Schema and frontmatter validation
+
+- Confirm required fields are present, correctly named, and correctly typed.
+- Confirm no field was invented that the schema does not define.
+- Validate against the project's own schema or validator where one exists,
+  rather than eyeballing the shape.
+
+### 3. The artifact builds
+
+- Run the project's build for the affected area and confirm it exits cleanly.
+- Run the relevant tests, linter, and type checker. Report actual output; do not
+  assert success you did not observe.
+- If the build cannot be run in this environment, say so plainly and name what
+  remains unverified.
+
+### 4. Links and referenced paths resolve
+
+- Confirm every file path referenced in the output exists.
+- Confirm internal links point at real anchors, routes, or documents.
+- For external URLs, confirm they were reachable when checked, or mark them as
+  unchecked.
+
+### Reporting
+
+State plainly what passed, what failed, and what you could not check. A partial
+result reported accurately is more useful than a clean summary that hides a gap.
+<!-- aidlc:verify-steps:end -->
+
+## Why verification is built in
+
+An operational skill runs repeatedly, often unattended, and its output usually
+lands directly in a repository or a published surface. The failure mode is not a
+crash — it is plausible-looking output that nobody checked. Embedding these steps
+in the skill body means the check travels with the operation rather than depending
+on whoever happens to invoke it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasensio/aidlc-content",
-  "version": "1.8.1",
+  "version": "1.9.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/00-overview.md

@@ -28,6 +28,44 @@ The AIDLC defines seven ordered phases. Not all apply to every task:
 | Standard | Requirements | Requirements through Deployment |
 | Micro | Implementation | Implementation and Testing only |
 
+## Lifecycle or Skill?
+
+**The rule: lifecycle for changes to the system; skills for repeatable operations of the system.**
+
+Not every task belongs in a lifecycle instance. Ask which of the two a request is:
+
+- **A change to the system** — a new capability, a fix, a refactor, anything that alters what the
+  system can do. This goes through the lifecycle: phases, artifacts, gates.
+- **A repeatable operation of the system** — running a chore the system already supports, over and
+  over, with the same steps each time. This belongs in a **skill**, not an instance.
+
+Worked example, a blog application:
+
+| Request | Which | Why |
+|---|---|---|
+| "Add a series feature so posts can belong to a series" | **Lifecycle** | The system cannot do this yet. New capability → requirements, design, tests. |
+| "Publish a post about last week's release" | **Skill** | The system already supports posts. Same steps every time. Wrapping each post in phases is ceremony. |
+
+Running an operational skill is **never** a lifecycle instance. Do not create an instance, claim, or
+phase artifacts to publish a post, rotate a log, or regenerate a report.
+
+### The escape hatch
+
+An operation sometimes reveals a missing capability — you go to publish a post and discover the system
+has no way to mark it as a draft. When that happens, the *operation* stops being the work and the
+missing capability re-enters the lifecycle as a normal instance. Capture it with **aidlc-idea** or start
+an instance; do not quietly extend the skill into building the feature.
+
+### Quality mechanisms live inside the skill
+
+An operational skill's output still needs checking — facts verified, schema validated, the build run,
+links resolved. Those checks belong **inside the skill's own instructions**, not as lifecycle phases
+wrapped around each invocation. A skill that carries its own verification produces checked output every
+time it runs; a skill that relies on a review phase produces checked output only when someone remembers
+to run one.
+
+`aidlc add skill` scaffolds an operational skill with verification steps already embedded.
+
 ## State Protocol
 
 All state lives in `.aidlc/state/<instance-name>/`. Read and write state as follows:

package/skills/01-getting-started.md

@@ -41,6 +41,17 @@ Create an instance from the template that fits:
 - 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.
@@ -91,6 +102,7 @@ If not installed yet, run `npx @rasensio/aidlc init` in a terminal. Installation
 | 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/`.
 

package/skills/83-add-skill.md

@@ -0,0 +1,127 @@
+---
+name: aidlc-add-skill
+description: Turns a described repeatable operation into an app-owned operational skill with built-in verification
+phase: implementation
+priority: 54
+---
+# Operational Skill Authoring
+
+## Purpose
+
+Turn a plain-language description of a repeatable operation into a working skill in the user's repo —
+one canonical body plus platform-native packaging, with verification steps already embedded.
+
+**Authoring a skill is not performing the operation.** You are writing instructions for later, not
+running them now. Never execute the described operation while authoring it: do not publish the post, do
+not run the deployment, do not send the message. If the user wants the operation performed, that is a
+separate request made after the skill exists.
+
+## When to Use This
+
+The user describes something they do **repeatedly** with the **same steps** — publishing a post,
+rotating credentials, regenerating a report, cutting a release note.
+
+Before generating anything, apply the rule from **aidlc-overview**: *lifecycle for changes to the
+system; skills for repeatable operations of the system.*
+
+## Instructions
+
+### 1. Check it is really an operation, not a system change
+
+If the description is really a new capability — the system cannot do this yet, and doing it once requires
+building something — say so plainly and offer the alternative:
+
+> "This sounds like a change to the system rather than a repeatable operation of it: <reason>. That
+> usually belongs in the lifecycle. I can capture it as an idea (`aidlc-idea`) or start an instance
+> instead. Or if you would rather have the skill anyway, say so and I will generate it."
+
+**If the user disagrees, generate the skill.** A false positive must never be a dead end — the user knows
+their workflow better than this heuristic does.
+
+Signals it is a **system change**: "add support for", "make it possible to", "we can't currently".
+Signals it is an **operation**: "every time I", "the steps are always", "I keep having to".
+
+### 2. Elicit what the skill needs
+
+Gather these before generating. Ask only for what is missing or genuinely ambiguous — do not
+interrogate the user for fields you can infer from what they already said.
+
+- **Name** — lowercase, hyphens, starts with a letter. The `aidlc-` prefix is reserved for framework
+  skills and will be rejected. Suggest one derived from the description and confirm it.
+- **Description** — one line: what operation this performs.
+- **Trigger** — when this skill should be used, in the user's own words.
+- **Steps** — the concrete operation, as ordered markdown. This is the substance; get it specific.
+  Vague steps produce a skill that cannot be followed.
+- **Conventions it must honour** — paths, naming schemes, frontmatter fields, index files to update,
+  commands to run. These are what make the difference between a skill that works in *this* repo and
+  generic advice.
+- **Paths** — repo-relative paths the operation touches. These are checked for existence by the
+  skill's own smoke test, so list real ones.
+
+### 3. Never put credential values in the skill
+
+Environment variable names and secret-manager references are legitimate and should be **kept**:
+`$GITHUB_TOKEN`, `op://vault/ci/token`, `arn:aws:secretsmanager:...`. Actual token values must not
+appear. If the user pastes one, tell them, leave it out, and reference it by variable name instead.
+
+Generation redacts detected credential values automatically before showing you a preview, but that
+detection is best-effort — do not rely on it in place of not asking for secrets.
+
+### 4. Generate
+
+Run the command. It renders a preview, asks for confirmation, and writes nothing until confirmed:
+
+```
+aidlc add skill <name> \
+  --description "<one line>" \
+  --steps "<the ordered steps, as markdown>" \
+  --trigger "<when to use it>" \
+  --paths <path> [<path>...]
+```
+
+Add `--dry-run` first if the user wants to see the output without a prompt.
+
+The command owns the write path: it validates the name, redacts credentials before rendering the
+preview, asks for confirmation, writes all files or none, runs a smoke check, and registers the skill in
+the knowledge graph. Do not reimplement any of that by writing the files yourself — the confirmation is a
+security boundary, because a generated skill is instructions an agent will later execute.
+
+### 5. Report what happened
+
+Tell the user which files were written, whether the smoke check passed, and whether knowledge-graph
+registration succeeded. A registration warning is not a failure — the skill still works.
+
+If the smoke check reports a missing declared path, that usually means a `--paths` entry was wrong, not
+that the skill is broken. Offer to re-run with corrected paths.
+
+## Other Modes
+
+- **`aidlc add skill --check [<name>]`** — verify existing skills parse, carry verification text, and
+  that their declared paths exist. Run this if a skill has been hand-edited.
+- **`aidlc add skill --re-emit [<name>]`** — re-package for the currently configured platforms and
+  refresh the verification text from the installed content package. Use it after adding a platform to
+  `.aidlc/config.yaml`, after upgrading the content package, or to repair a skill whose knowledge-graph
+  entry is missing. It never rewrites the user's own steps.
+- **`aidlc add skill <name> --overwrite`** — replace an existing skill. Generation refuses a name
+  collision by default rather than silently overwriting.
+
+## What Not to Do
+
+- Do not create a lifecycle instance to run a generated skill. Running an operation is never an instance.
+- Do not author the skill by writing `.aidlc/operational-skills/<name>.md` directly. That bypasses name
+  validation, redaction, atomic writes, and the confirmation gate.
+- Do not remove or edit the verification section in a generated skill. It is machine-managed, delimited
+  by `<!-- aidlc:verify-steps:begin -->` / `<!-- aidlc:verify-steps:end -->`, and `--re-emit` refreshes
+  it. Content outside those markers is yours to edit freely.
+- Do not use the `aidlc-` prefix. It is reserved and enforced.
+
+## Exit Criteria
+
+- The skill's canonical body and platform files are written (on confirmation), the smoke check has run,
+  and its result was reported — **or**
+- The user declined, and the working tree is unchanged — **or**
+- The request was a system change and the user chose the lifecycle instead.
+
+## Guidance
+
+{{context:style-guide}}