@alexandrealvaro/agentic 0.8.0-beta.1 → 0.9.1-beta.1

package/WORKFLOW.md

@@ -25,6 +25,7 @@ What to keep in mind:
 13. **Automation needs rails.** Hooks, tests, lint, CI, sandboxing, and permissions matter more than advisory text the agent can forget.
 14. **Autonomy requires observability.** If the agent makes decisions, log the trajectory: tool calls, intermediate outputs, failures.
 15. **Staged spikes when the technique is uncertain.** When the *how* is unknown — a library choice, a CV technique, a multi-stage transformation — break the problem into staged spikes against golden fixtures with per-stage debug artifacts.
+16. **Discipline scales with project maturity.** Same principles bind every project; the artifact set scales. A spike runs posture + research + audit; a regulated product adds spec / ADR / hooks / evals. The toolkit amplifies what the project needs — never imposes ceremony beyond it. Configurable at init; changeable as the project matures.
 
 > Working with agents means trading typing for technical direction. The value is in giving the right context, setting boundaries, validating the result, and keeping "almost right" out of production.
 
@@ -41,6 +42,8 @@ There are two complementary frames for the artifacts the kit produces. The first
 3. **Plan / Decisions** — `ARCHITECTURE.md` (system patterns and boundaries), `doc/adr/NNNN-*.md` (binding architectural decisions in Michael Nygard's pattern), `doc/tasks/NNNN-*.md` (per-work-unit plan with checkbox acceptance criteria). The *how* of building what the spec asked for.
 4. **Code** — the implementation. Code is the primary documentation of behavior; comments justify non-obvious choices.
 
+The four layers scale with project maturity (TL;DR #16). A spike or PoC profile may legitimately ship only Layers 1 and 4 — adding Layers 2 and 3 to a 200-line experiment is ceremony that does not change agent behavior. A team or regulated product runs all four. The kit's profiles (`poc`, `solo`, `team`, `mature`) configure which layers auto-install per project and are changeable as the project matures; the principles in this document bind every profile, only the artifact set differs.
+
 ### Three context types (loading mechanism)
 
 - **Operational context is advisory.** `AGENTS.md` (or `CLAUDE.md` for Claude Code, which can mirror or import the same content via `@AGENTS.md`) tells the agent how to build, test, follow conventions, and where the security boundaries are. The agent reads it as a guide, not a contract. Open standard `AGENTS.md` is native in most agentic IDEs.
@@ -88,6 +91,8 @@ Use XML when the prompt mixes instructions, retrieved context, examples, user in
 
 No format is universally best. **An observation from my practice, not benchmarked:** I've seen consistent gains when shifting prompts to XML — most noticeably with autonomous agents, where the prompt has to land alone without conversational refinement. Direct interactive use (Claude Code, Codex) tolerates loose Markdown; unattended agents don't. Claude in particular seems to respond well to XML, which I attribute to its training, but I haven't benchmarked it. Treat this as a starting hypothesis worth testing on your own target model and task before standardizing.
 
+**Host-aware structured prompts.** Hosts that expose structured-prompt primitives — Claude Code's `AskUserQuestion` (multi-choice cards) and Plan Mode (plan-approval cards) — reduce ambiguity at confirmation gates more reliably than inline text. Prefer the structured primitive when the host supports it; fall back to numbered text otherwise. Codex has no equivalent today; its skills stay on numbered text. Skills carrying confirmation gates or multi-choice interview steps prescribe this preference (ADR-0014).
+
 ## 4–5. Research Before Implementation
 
 Combines Find the Happy Path (canonical / idiomatic baseline) and Ground in Real Patterns (anchoring in project-specific examples). The kit treats both as one indivisible flow via `agentic-ground`; two prose sections would frame one operation as two separate practices.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexandrealvaro/agentic",
-  "version": "0.8.0-beta.1",
+  "version": "0.9.1-beta.1",
   "description": "Bootstrap and audit AGENTS.md, ARCHITECTURE.md, ADRs, skills, and subagents for engineering production code with LLMs",
   "type": "module",
   "bin": {

package/src/skills/claude-code/agentic-adr/SKILL.md

@@ -24,6 +24,10 @@ Use the template below. Fill `Context`, `Decision`, `Consequences`, and `Alterna
 * `Consequences` lists positive and negative; do not balance for the sake of balance.
 * `Alternatives Considered` lists each rejected option with a one-line reason.
 
+## Interview UX
+
+When the host exposes `AskUserQuestion`, use it for multi-choice prompts (`Status: proposed / accepted / deprecated / superseded`, decider role selection, alternative-option ranking) and for confirmation gates with non-trivial branching. Inline text questions are the fallback only when the host lacks a structured-prompt primitive (Codex). One card per multi-choice gate beats chained text questions.
+
 ## Step 4 — Write the file
 
 Path: `doc/adr/<NNNN>-<short-slug>.md`. Slug: kebab-case, ≤6 words, derived from the decision title. Status: `proposed`. Date: today, ISO format. Deciders: ask the user.

package/src/skills/claude-code/agentic-architecture/SKILL.md

@@ -42,6 +42,8 @@ Print to the user:
 
 One question per gap.
 
+When the host exposes Plan Mode, the agent may render the proposed `ARCHITECTURE.md` body inside the plan for user approval before write. Plan Mode is opt-in — skip for incremental edits where the user already saw the prior content.
+
 ## Step 4 — Write the file
 
 On user confirmation, write `ARCHITECTURE.md` at the repo root. Cut every line that does not lock a binding pattern. At the end of the response, list any decision that should become an ADR — flag, do not write the ADR yet (use the `agentic-adr` skill for that).

package/src/skills/claude-code/agentic-bootstrap/SKILL.md

@@ -44,6 +44,8 @@ Print to the user:
 
 One question per gap. Skip everything filled confidently. Do **not** ask philosophical questions ("is this doc for agents or humans?", "what is the most important quality bar?") — those are decisions, not interview material.
 
+When the host exposes Plan Mode, the agent may render the proposed `AGENTS.md` body inside the plan (the user reviews and approves before write) instead of writing-then-presenting. Plan Mode is opt-in — skip for incremental edits where the user already saw the prior content.
+
 ## Step 4 — Write the file
 
 On user confirmation, write `AGENTS.md` at the repo root. Cut every line that does not change agent behavior. No "External Resources" section (URLs are derivable from `git remote` and the manifest). No appended Universal Agent Behavior block. No marketing prose.

package/src/skills/claude-code/agentic-ground/SKILL.md

@@ -55,6 +55,8 @@ Before handing off to implementation, report a soft verdict against four checks:
 
 If any check fails, surface the gap to the user and ask before proceeding rather than blocking. The user retains the authority to skip; the discipline is in surfacing, not in enforcement.
 
+When the host exposes `AskUserQuestion`, render the checkpoint as a structured multi-choice card listing the six checks with their yes/no/n.a. status plus a final `proceed / pause for more research` selector — instead of dropping the verdict as plain text. Falls back to numbered text on hosts without the primitive (Codex).
+
 ## Output contract
 
 A single message structured as:

package/src/skills/claude-code/agentic-review/SKILL.md

@@ -18,6 +18,8 @@ Confirm what to review. Default scopes, in priority order:
 
 If no diff exists, stop and tell the user — there's nothing to review.
 
+When the host exposes `AskUserQuestion`, use it at Step 0 to confirm the review scope as a multi-choice card (`branch vs main / PR#NN / commit-sha / working-tree`) instead of asking inline text. Falls back to numbered text on hosts without the primitive (Codex).
+
 ## Step 1 — Assemble the handoff
 
 The reviewer subagent will get **only** what you assemble here. No conversation history, no prior context.

package/src/skills/claude-code/agentic-spec/SKILL.md

@@ -32,6 +32,10 @@ Ask one question per missing field, in this order. Skip the philosophical questi
 
 Status starts at `draft`. Created: today, ISO format. Owner: ask. Do **not** invent values — when the user does not know, leave `<TODO>` and ask.
 
+## Interview UX
+
+When the host exposes `AskUserQuestion`, use it for multi-choice prompts (`Status: draft / accepted / shipped`, owner selection from team members, scope-vs-multiple-features confirmation) and for confirmation gates with non-trivial branching. Inline text questions are an acceptable fallback only when the host lacks a structured-prompt primitive (Codex). One question per gate; do not chain three text questions when one `AskUserQuestion` card lists the options.
+
 ## Step 4 — Write the file
 
 Path: `doc/specs/<NNNN>-<short-slug>.md`. Use the template below.

package/src/skills/claude-code/agentic-task/SKILL.md

@@ -27,6 +27,10 @@ Status starts at `proposed`. Created: today, ISO format. Notes: empty (filled du
 
 **Do not invent values.** When the user does not know something, leave `<TODO>` and ask. Stop after writing the file — do not start work.
 
+## Interview UX
+
+When the host exposes `AskUserQuestion`, use it for multi-choice prompts (status, owner selection, Spec-ref pick from existing `doc/specs/`) and for confirmation gates with non-trivial branching. Inline text questions are the fallback only when the host lacks a structured-prompt primitive (Codex). Single card per multi-choice gate beats chained text questions.
+
 ## Step 3 — Write the file
 
 Path: `doc/tasks/<NNNN>-<short-slug>.md`. Use the template below.