@alexandrealvaro/agentic 0.10.0-beta.1 → 0.11.1-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexandrealvaro/agentic",
-  "version": "0.10.0-beta.1",
+  "version": "0.11.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

@@ -71,3 +71,10 @@ ADRs are decision-record artifacts and are **exempt** from the no-dates rule (Do
 - `Context` is the business-context-first section — the *forces* and *problem* before the *decision*.
 - One scope: one decision per ADR. If the user's request implies multiple decisions, ask which one to write first; the others become follow-up ADRs.
 - No speculation. `Decision` is a directive ("We will…"); rejected paths go in `Alternatives Considered`, not the body.
+
+## Next
+
+- Continue the work the ADR was scoped to support. Status starts `proposed`; the user flips to `accepted` after review (the agent does not).
+- If the ADR touches `ARCHITECTURE.md`'s Active ADRs list, add the entry there.
+- `/agentic-task` for the work units that implement the decision.
+- `/agentic-audit` periodically to confirm the decision still holds against the code.

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

@@ -112,3 +112,9 @@ A single `ARCHITECTURE.md` at the repo root. Every line locks a binding pattern.
 - `Overview` is the business-context-first paragraph — *what the system does* and *what would break without it* before layers and patterns.
 - One scope: system-level patterns and boundaries. Per-decision rationale lives in ADRs; per-project operations live in `AGENTS.md`. Link, do not copy.
 - No speculation. If a layer has no observed signal, write `<TODO: not yet wired>` once; do not propose patterns that aren't already in the code.
+
+## Next
+
+- `/agentic-spec` when starting a feature whose scope spans the patterns this document records.
+- `/agentic-adr` for any binding decision that surfaced while writing or auditing this file (one decision per ADR).
+- `/agentic-audit` periodically to check pattern drift between this document and the code.

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

@@ -74,3 +74,10 @@ If something the user says contradicts what the code shows, surface the conflict
 ## Output contract
 
 A drift list, no file written. Read-only operation. Empty result is reported explicitly ("no drift found across audited artifacts"), not silently. Missing artifacts are flagged, not skipped.
+
+## Next
+
+- Address each finding with one of the three resolutions named in the format ("change spec / change code / discuss").
+- For findings that require implementation: `/agentic-task` to scaffold the fix.
+- For workflow drift (where am I, what's stuck): `/agentic-next`.
+- For kit-version drift (state file behind current kit): `agentic update`.

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

@@ -161,3 +161,10 @@ A single `AGENTS.md` at the repo root, ≤150 lines, every line operational. No
 - `Project Overview` is the business-context-first paragraph — *why* the project exists before *what* it does.
 - One scope: this file is the operational guide for agents. Do not duplicate `ARCHITECTURE.md` patterns or ADR rationale here; link instead.
 - No speculation. If a section has no signal, write `<TODO: not yet wired>` once; do not narrate "this could be added later".
+
+## Next
+
+- In `team` / `mature`: run `/agentic-architecture` once load-bearing patterns emerge in the code.
+- When you start your first feature: `/agentic-spec` (Layer 2 of the four-layer artifact stack).
+- Skip both above in `poc` / `solo` until the project genuinely needs them — the WORKFLOW §1 prune principle applies.
+- `agentic-philosophy` auto-loads on non-trivial work; no explicit invocation needed.

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

@@ -69,3 +69,9 @@ A single `DESIGN.md` at the repo root. YAML frontmatter uses W3C `$value`/`$type
 - The Markdown body opens with the *why* of each token group — the visual constraint or product principle — before listing rules.
 - One scope: visual contract. Component anatomy and interaction patterns belong elsewhere; link, do not copy.
 - No speculation. If a group has no source token, mark `<TODO: not yet wired>` and move on.
+
+## Next
+
+- `/agentic-spec` for any feature whose scope touches the visual contract this document records.
+- `/agentic-audit` (DESIGN.md drift category) periodically when tokens change in the source.
+- `/agentic-adr` for binding visual decisions worth recording as architectural commitments (e.g., dropping a token category).

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

@@ -100,3 +100,10 @@ A single message structured as:
 ```
 
 No code is written by this skill. The output feeds the next turn (or `/agentic-task`, `/agentic-philosophy`'s Goal-Driven Execution, or freeform implementation).
+
+## Next
+
+- Implement per the synthesized happy path. Cite the sources you grounded against in commit messages or task `Notes`.
+- `/agentic-task` if the work needs explicit decomposition into checkbox-toggle work units.
+- `/agentic-review main..HEAD` (or current scope) before merge — WORKFLOW §10.
+- `/agentic-adr` if the deviation gate surfaced a binding architectural decision.

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

@@ -95,3 +95,10 @@ A narrative document, so the documentation discipline rules apply at write time:
 - The Quality Gates section opens with the operational rule (gates are deterministic) before listing the gates themselves.
 - One scope: Quality Gates. Do not duplicate ARCHITECTURE.md or ADR rationale here.
 - No commented-out scripts. No orphan TODO / FIXME — every deferred command references a tracked task or GitHub Issue.
+
+## Next
+
+- Run the runner's bootstrap command (cited in Step 5 — e.g., `npm install`, `lefthook install`, `pre-commit install`).
+- Verify a deliberately-failing edit (e.g., a known lint violation) gets blocked at commit. The gate is real only when it actually fires.
+- Add a redundant CI gate (`.github/workflows/`, GitLab CI, or equivalent) so contributors cannot bypass via `--no-verify`. WORKFLOW §11 binding.
+- `/agentic-audit` periodically to confirm hooks stay wired as the project evolves.

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

@@ -98,3 +98,10 @@ Strong success criteria let you loop independently. Weak criteria ("make it work
 8. **Tests are living documentation of behavior.** Test names and assertions read as the spec they enforce. Spec changes drive test changes; never the reverse.
 
 When generating or auditing a document, walk this list before declaring done.
+
+## Next
+
+- Continue current work with the six behaviors active. This skill is posture, not a one-shot task.
+- `/agentic-ground` for non-trivial research before code.
+- `/agentic-next` when uncertain where to go in the workflow.
+- `/agentic-review` before merging non-trivial diffs.

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

@@ -52,3 +52,10 @@ If the subagent reports zero findings across all severities, say so explicitly (
 ## Output contract
 
 A structured findings list grouped Blocker / Concern / Note, each finding `file:line: <severity>: <problem>. <fix>.`. The path of the persisted handoff under `.agentic/reviews/` is reported alongside. No "approve" verdict, no defending of the code, no rewrite of the diff. Empty result is reported explicitly.
+
+## Next
+
+- Address every Blocker before merge. Re-run `/agentic-review` on the fix to confirm it cleared.
+- Each Concern becomes a follow-up `/agentic-task`; do not let them silently accumulate.
+- Notes are informational; close them out in the original task's `Notes` log if relevant.
+- Once Blockers are clear: merge per project conventions.

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

@@ -49,3 +49,9 @@ Do not invoke the new skill, do not pre-fill it with example content, do not tes
 ## Output contract
 
 A single new `SKILL.md` at the chosen path (plus `agents/openai.yaml` for Codex). Frontmatter declares only the fields actually used. Body is imperative and terse. No external file dependencies the user did not ask for.
+
+## Next
+
+- Test the new skill's description triggers by invoking it from a real conversation — verify auto-triggering on the keywords you chose.
+- If the skill is meant to be universal across the kit's profiles, propose an ADR + Task to add it to the profile catalog (`src/lib/profiles.js`) — universal additions are kit-level decisions, not single-project ones.
+- If the skill carries a sibling subagent, declare it in `manifest.json` and add the source under `agents/`.

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

@@ -127,3 +127,10 @@ The spec is a narrative document but is exempt from ADR-0008's no-dates rule for
 - One scope: one feature per spec. Multiple features implies multiple specs.
 - No speculation. Open Questions go in their named section; everywhere else captures decisions.
 - No commented-out requirements or TODO/FIXME — every deferred item references a tracked work item or lives under Open Questions.
+
+## Next
+
+- `/agentic-ground` for the four-source research pass before code (WORKFLOW §4 + §5).
+- `/agentic-task` to break the spec into work units; each task carries a `Spec ref` field pointing back to this file.
+- `/agentic-adr` if scoping the spec surfaced a binding architectural decision worth recording (one decision per ADR).
+- Flip Status to `accepted` once you sign off and tasks start being created. Flip to `shipped` after release.

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

@@ -57,3 +57,9 @@ Do not dispatch to the new subagent, do not test it. The user will exercise it t
 ## Output contract
 
 A single new file at `.claude/agents/<name>.md` (or `~/.claude/agents/<name>.md`). Frontmatter declares only the fields actually used. Body is the system prompt: terse, imperative, with explicit stop criterion. No external file dependencies the user did not ask for.
+
+## Next
+
+- Test the new subagent by exercising the workflow it serves — invoke via the `Task` tool with `subagent_type: '<name>'`.
+- Document the subagent in `AGENTS.md` (or the project's operational guide) if it is project-wide rather than personal.
+- If the subagent ships alongside a skill (manifest-listed), update the skill's `manifest.json` to declare the file.

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

@@ -105,3 +105,10 @@ Task files are decision-record artifacts and are **exempt** from the no-dates ru
 - One scope: one task per file. If the user's request implies multiple deliverables, ask which to write first; the others become follow-up tasks.
 - No speculation. Acceptance criteria must be measurable; do not list aspirational items ("loads in under 2s", not "fast enough").
 - `Notes` is append-only and dated per entry — that is the auditability primitive, not a violation of Rule 2.
+
+## Next
+
+- Implement. Toggle Acceptance Criteria checkboxes and append to `Notes` as work lands.
+- `/agentic-review main..HEAD` (or current scope) before merge — the task DoD requires a fresh-context §10 review.
+- Flip Status to `done` once every Acceptance Criterion and Definition-of-Done item is checked.
+- If the task implements a spec, the spec's `Related → Tasks` list should reciprocate the link.

package/src/skills/codex/agentic-adr/SKILL.md

@@ -57,3 +57,10 @@ ADRs are decision-record artifacts and are exempt from the no-dates rule (Docume
 - One scope: one decision per ADR.
 - No speculation. `Decision` is a directive; rejected paths go in `Alternatives Considered`.
 </output_contract>
+
+## Next
+
+- Continue the work the ADR was scoped to support. Status starts `proposed`; the user flips to `accepted` after review (the agent does not).
+- If the ADR touches `ARCHITECTURE.md`'s Active ADRs list, add the entry there.
+- `/agentic-task` for the work units that implement the decision.
+- `/agentic-audit` periodically to confirm the decision still holds against the code.

package/src/skills/codex/agentic-architecture/SKILL.md

@@ -93,3 +93,9 @@ A single `ARCHITECTURE.md` at the repo root. Every line locks a binding pattern.
 - One scope: system-level patterns and boundaries. Per-decision rationale lives in ADRs; per-project operations live in `AGENTS.md`. Link, do not copy.
 - No speculation. If a layer has no observed signal, write `<TODO: not yet wired>` once; do not propose patterns absent from the code.
 </output_contract>
+
+## Next
+
+- `/agentic-spec` when starting a feature whose scope spans the patterns this document records.
+- `/agentic-adr` for any binding decision that surfaced while writing or auditing this file (one decision per ADR).
+- `/agentic-audit` periodically to check pattern drift between this document and the code.

package/src/skills/codex/agentic-audit/SKILL.md

@@ -58,3 +58,10 @@ If something the user says contradicts what the code shows, surface the conflict
 <output_contract>
 A drift list, no file written. Read-only operation. Empty result is reported explicitly ("no drift found across audited artifacts"), not silently. Missing artifacts are flagged, not skipped.
 </output_contract>
+
+## Next
+
+- Address each finding with one of the three resolutions named in the format ("change spec / change code / discuss").
+- For findings that require implementation: `/agentic-task` to scaffold the fix.
+- For workflow drift (where am I, what's stuck): `/agentic-next`.
+- For kit-version drift (state file behind current kit): `agentic update`.

package/src/skills/codex/agentic-bootstrap/SKILL.md

@@ -143,3 +143,10 @@ A single `AGENTS.md` at the repo root, ≤150 lines, every line operational. No
 - One scope: this file is the operational guide for agents. Do not duplicate `ARCHITECTURE.md` patterns or ADR rationale here; link instead.
 - No speculation. If a section has no signal, write `<TODO: not yet wired>` once; do not narrate "this could be added later".
 </output_contract>
+
+## Next
+
+- In `team` / `mature`: run `/agentic-architecture` once load-bearing patterns emerge in the code.
+- When you start your first feature: `/agentic-spec` (Layer 2 of the four-layer artifact stack).
+- Skip both above in `poc` / `solo` until the project genuinely needs them — the WORKFLOW §1 prune principle applies.
+- `agentic-philosophy` auto-loads on non-trivial work.

package/src/skills/codex/agentic-design/SKILL.md

@@ -53,3 +53,9 @@ A single `DESIGN.md` at the repo root. YAML frontmatter uses W3C `$value`/`$type
 - One scope: visual contract. Component anatomy and interaction patterns live elsewhere; link, do not copy.
 - No speculation. If a group has no source token, mark `<TODO: not yet wired>` and move on.
 </output_contract>
+
+## Next
+
+- `/agentic-spec` for any feature whose scope touches the visual contract this document records.
+- `/agentic-audit` (DESIGN.md drift category) periodically when tokens change in the source.
+- `/agentic-adr` for binding visual decisions worth recording as architectural commitments.

package/src/skills/codex/agentic-ground/SKILL.md

@@ -80,3 +80,10 @@ A single message structured as:
 
 No code is written by this skill. The output feeds the next turn or another skill.
 </output_contract>
+
+## Next
+
+- Implement per the synthesized happy path. Cite the sources you grounded against in commit messages or task Notes.
+- `/agentic-task` if the work needs explicit decomposition into checkbox-toggle work units.
+- `/agentic-review main..HEAD` (or current scope) before merge — WORKFLOW §10.
+- `/agentic-adr` if the deviation gate surfaced a binding architectural decision.

package/src/skills/codex/agentic-hooks/SKILL.md

@@ -60,3 +60,10 @@ Documentation discipline rules apply at write time:
 - One scope: Quality Gates. No duplication of ARCHITECTURE.md or ADR rationale.
 - No commented-out scripts. No orphan TODO / FIXME.
 </output_contract>
+
+## Next
+
+- Run the runner's bootstrap command (cited in Step 5 — e.g., `npm install`, `lefthook install`, `pre-commit install`).
+- Verify a deliberately-failing edit (e.g., a known lint violation) gets blocked at commit.
+- Add a redundant CI gate so contributors cannot bypass via `--no-verify`. WORKFLOW §11 binding.
+- `/agentic-audit` periodically to confirm hooks stay wired as the project evolves.

package/src/skills/codex/agentic-philosophy/SKILL.md

@@ -37,3 +37,10 @@ Walk this list before declaring any documentation task done.
 <output_contract>
 This skill emits no file. Its job is to set the agent's working posture for the next non-trivial change.
 </output_contract>
+
+## Next
+
+- Continue current work with the six behaviors active. This skill is posture, not a one-shot task.
+- `/agentic-ground` for non-trivial research before code.
+- `/agentic-next` when uncertain where to go in the workflow.
+- `/agentic-review` before merging non-trivial diffs.

package/src/skills/codex/agentic-review/SKILL.md

@@ -75,3 +75,10 @@ Do not proceed past this point in the current session.
 <output_contract>
 A handoff file at `.agentic/reviews/<ISO-timestamp>-<scope-slug>.md`, plus a short instruction telling the user how to load it into a fresh Codex session via `/clear` and paste. The current session does not produce findings — the fresh session does, after the user re-loads the handoff. This honors WORKFLOW §10 by enforcing context isolation through `/clear` rather than via a subagent primitive Codex lacks; the persisted file replaces the chat-scroll copy step that previously made the round-trip fragile.
 </output_contract>
+
+## Next
+
+- Address every Blocker before merge. Re-run `/agentic-review` on the fix to confirm it cleared.
+- Each Concern becomes a follow-up `/agentic-task`; do not let them silently accumulate.
+- Notes are informational; close them out in the original task's `Notes` log if relevant.
+- Once Blockers are clear: merge per project conventions.

package/src/skills/codex/agentic-skill/SKILL.md

@@ -40,3 +40,9 @@ Step 4 — stop after writing. Do not invoke the new skill, do not pre-fill it w
 <output_contract>
 A single new `SKILL.md` at the chosen path (plus `agents/openai.yaml` for Codex). Frontmatter declares only the fields actually used. Body is imperative and terse. No external file dependencies the user did not ask for.
 </output_contract>
+
+## Next
+
+- Test the new skill's description triggers by invoking it from a real conversation — verify auto-triggering on the keywords you chose.
+- If the skill is meant to be universal across the kit's profiles, propose an ADR + Task to add it to the profile catalog (`src/lib/profiles.js`).
+- If the skill carries a sibling subagent, declare it in `manifest.json` and add the source under `agents/`.

package/src/skills/codex/agentic-spec/SKILL.md

@@ -103,3 +103,10 @@ Spec is a narrative document but is exempt from ADR-0008's no-dates rule for the
 - No speculation. Open Questions go in their named section.
 - No commented-out requirements or TODO/FIXME — every deferred item references a tracked work item or lives under Open Questions.
 </output_contract>
+
+## Next
+
+- `/agentic-ground` for the four-source research pass before code (WORKFLOW §4 + §5).
+- `/agentic-task` to break the spec into work units; each task carries a `Spec ref` field pointing back to this file.
+- `/agentic-adr` if scoping the spec surfaced a binding architectural decision.
+- Flip Status to `accepted` once you sign off and tasks start being created. Flip to `shipped` after release.

package/src/skills/codex/agentic-task/SKILL.md

@@ -89,3 +89,10 @@ Task files are decision-record artifacts and are exempt from the no-dates rule (
 - No speculation. Acceptance criteria must be measurable; do not list aspirational items.
 - `Notes` is append-only and dated per entry — that is the auditability primitive, not a violation of Rule 2.
 </output_contract>
+
+## Next
+
+- Implement. Toggle Acceptance Criteria checkboxes and append to `Notes` as work lands.
+- `/agentic-review main..HEAD` (or current scope) before merge — the task DoD requires a fresh-context §10 review.
+- Flip Status to `done` once every Acceptance Criterion and Definition-of-Done item is checked.
+- If the task implements a spec, the spec's `Related → Tasks` list should reciprocate the link.