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

package/README.md

@@ -39,6 +39,7 @@ Two categories ([ADR-0007](doc/adr/0007-workflow-operational-skills.md)) and two
 | `agentic-philosophy` | workflow-operational | universal | Universal agent guardrails — auto-loads on non-trivial work | implicit |
 | `agentic-review` | workflow-operational | universal | Fresh-context code review per WORKFLOW §10; structured findings, no "approve" | `/agentic-review <range>` |
 | `agentic-ground` | workflow-operational | universal | Four-source pre-implementation research (docs / OSS / in-repo / git history) + happy-path synthesis + deviation gate per WORKFLOW §4 + §5 | `/agentic-ground` |
+| `agentic-next` | workflow-operational | universal | State-aware navigation aid (`flutter doctor` pattern) — surveys the four-layer artifact stack and recommends prioritized next actions; complements `agentic-audit` (drift) | `/agentic-next` |
 | `agentic-design` | spec-driven | auto if frontend detected | Bootstrap `DESIGN.md` from existing tokens (Figma, tailwind.config, tokens.json, CSS custom props) | `/agentic-design` |
 | `agentic-subagent` | spec-driven | auto if installing for Claude Code | Drafts `.claude/agents/<name>.md` (Claude Code only — Codex has no subagent primitive) | `/agentic-subagent` |
 | `agentic-skill` | spec-driven | opt-in only | Drafts a new Claude Code or Codex skill at the appropriate path | `/agentic-skill` |
@@ -152,6 +153,8 @@ The kit ships nine universal skills plus three conditional ones — twelve discr
 
 The kit's discipline scales with the project's maturity. A solo PoC may legitimately skip `/agentic-spec` and `/agentic-adr` (the WORKFLOW §1 prune principle applies — don't add an artifact that wouldn't change agent behavior). A team product running on this kit is expected to use the full sequence and additionally invoke `/agentic-hooks` once to scaffold the deterministic gates per WORKFLOW §11 (pre-commit lint / format / secret-scan; pre-push build / unit / integration). Project maturity profiles that automate the recommendation by stack are deferred — see the next planned release.
 
+**Lost mid-flow?** Invoke `/agentic-next` at any time to survey the project's state across the four-layer artifact stack (Constitution → Spec → Plan/Decisions → Code) and get prioritized next-action recommendations. Read-only; complements `/agentic-audit` (drift detection — different question).
+
 ## Manual prompts
 
 If you prefer to skip the installer, the same artifacts can be generated by pasting prompts directly into your agent. Each prompt file has the literal text to copy, plus the matching template structure:

package/package.json

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

@@ -340,6 +340,7 @@ export async function initCommand(opts) {
       '/agentic-audit',
       '/agentic-review (WORKFLOW §10)',
       '/agentic-ground (WORKFLOW §4 + §5)',
+      '/agentic-next (state survey + recommendations)',
       ...(optedSkills.includes('agentic-design') ? ['/agentic-design (DESIGN.md)'] : []),
       ...(optedSkills.includes('agentic-subagent') && agents.includes('claude-code')
         ? ['/agentic-subagent']

package/src/lib/profiles.js

@@ -20,7 +20,7 @@ export const PROFILE_NAMES = ['poc', 'solo', 'team', 'mature'];
 
 export const PROFILES = {
   poc: {
-    universal: ['agentic-philosophy', 'agentic-ground', 'agentic-audit'],
+    universal: ['agentic-philosophy', 'agentic-ground', 'agentic-audit', 'agentic-next'],
     conditional: {
       'agentic-design': 'blocked',
       'agentic-subagent': 'blocked',
@@ -34,6 +34,7 @@ export const PROFILES = {
       'agentic-philosophy',
       'agentic-ground',
       'agentic-audit',
+      'agentic-next',
       'agentic-bootstrap',
       'agentic-spec',
       'agentic-task',
@@ -60,6 +61,7 @@ export const PROFILES = {
       'agentic-audit',
       'agentic-review',
       'agentic-ground',
+      'agentic-next',
     ],
     conditional: {
       'agentic-design': 'frontend',
@@ -80,6 +82,7 @@ export const PROFILES = {
       'agentic-audit',
       'agentic-review',
       'agentic-ground',
+      'agentic-next',
     ],
     conditional: {
       'agentic-design': 'frontend',

package/src/lib/rootdoc.js

@@ -26,6 +26,8 @@ export const SKILL_DESCRIPTIONS = {
     'Fresh-context code review per WORKFLOW §10 — assemble handoff, return structured findings.',
   'agentic-ground':
     'Four-source pre-implementation research (docs / OSS / in-repo / git history) + happy-path synthesis + deviation gate. WORKFLOW §4 + §5.',
+  'agentic-next':
+    'State survey + prioritized next-action recommendations across the four-layer artifact stack. Read-only navigation aid (`flutter doctor` pattern).',
   'agentic-design': 'Bootstrap `DESIGN.md` from existing tokens (frontend projects).',
   'agentic-subagent': 'Draft a new Claude Code subagent at `.claude/agents/<name>.md`.',
   'agentic-skill': 'Draft a new Claude Code or Codex skill at the appropriate path.',

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

@@ -0,0 +1,119 @@
+---
+name: agentic-next
+description: Survey the project's state across the four-layer artifact stack and recommend prioritized next actions, modeled on `flutter doctor`. Use when the user asks "what's next", "next step", "where am I", "project status", "doctor", "what should I do", "audit my workflow", or whenever a navigation aid is needed mid-flow. Read-only; complements `agentic-audit` (drift detection, a different question). Profile-aware — `poc` suppresses Layer 2 / 3 noise, `team` / `mature` run the full survey.
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# /agentic-next
+
+Read-only state survey + prioritized next-action recommendations. Mirrors `flutter doctor` shape: layer-by-layer status + concrete fix per finding. Complements `agentic-audit` — audit answers "is anything wrong?", next answers "what should I do?".
+
+The skill writes nothing. Output is recommendations the user copies into the next conversation turn or the next CLI invocation.
+
+## Step 0 — Read state
+
+Detect baseline:
+
+* Profile + kit version: read `.claude/agentic-state.json` and `.agents/agentic-state.json` if present. Profile defaults to `team` per ADR-0013 when state file missing or no profile field.
+* Filesystem signals at the repo root: `AGENTS.md` / `CLAUDE.md`, `ARCHITECTURE.md`, `DESIGN.md`, `WORKFLOW.md`, `README.md`, `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod`, `.husky/` / `lefthook.yml` / `.pre-commit-config.yaml`, `.github/workflows/`, `.git/HEAD` (current branch).
+* Per-artifact directories: list `doc/specs/`, `doc/adr/`, `doc/tasks/`. Read each file's frontmatter (`Status:`, `Created:`, `Spec ref:` for tasks) but **not** the full body — survey is fast and broad.
+* Git state: current branch, commits ahead of `main` (`git rev-list --count main..HEAD`), unpushed commits, working-tree dirtiness.
+
+Do not parse skill bodies. Do not run tests. Do not invoke other skills. The survey is shallow by design.
+
+## Step 1 — Layer-by-layer status
+
+Render four sections in this exact order. For each section, list what is present, what is in flight, what is missing or stale. Use words for status (`present`, `in flight`, `missing`, `stale`) — no emoji.
+
+**Layer 1 — Constitution.**
+- `AGENTS.md` (or `CLAUDE.md`) present?
+- `WORKFLOW.md` present? (kit-shipped — should always be there)
+- `ARCHITECTURE.md` present?
+- `DESIGN.md` present? (frontend projects only)
+
+**Layer 2 — Specs (`doc/specs/`).**
+
+For each spec file, report `Status` and the count of tasks whose `Spec ref` field points at it:
+
+```
+0001-auth-flow.md (accepted, 0 implementing tasks)
+0002-onboarding.md (shipped, 3 tasks done)
+```
+
+Flag specs with `Status: accepted` and zero implementing tasks — that is the most common stuck state.
+
+**Layer 3 — Plans / Decisions.**
+
+`doc/adr/` — count by status: `proposed`, `accepted`, `deprecated`, `superseded`. Flag any `proposed` ADRs explicitly with their slug — they need a decision.
+
+`doc/tasks/` — count by status: `proposed`, `in-progress`, `blocked`, `done`. List in-progress and blocked tasks with their slugs and `Spec ref`. Flag tasks with no `Spec ref` and no `Board ref` as orphans (no clear scope tie).
+
+**Layer 4 — Code.**
+- Branch: `<name>` (`<n>` commits ahead of `main` if applicable).
+- Tests: wired? (presence of `npm test` script / `pytest` / `cargo test` / `go test ./...`).
+- Hooks: wired? (presence of `.husky/`, `lefthook.yml`, `.pre-commit-config.yaml`, or active `.git/hooks/` scripts).
+- CI: wired? (presence of `.github/workflows/`, `.gitlab-ci.yml`, `.circleci/`).
+
+## Step 2 — Cross-cut signals
+
+A few signals do not belong to one layer:
+
+- **Pending fresh-context review.** If branch is ≥1 commits ahead of `main` and no `.agentic/reviews/<ts>-*.md` exists for the current range, flag `agentic-review` as a recommendation.
+- **Spec ↔ task reciprocity.** Tasks with non-empty `Spec ref` whose target spec does not exist → orphan task. Specs with `Status: accepted` or `shipped` and zero entries in their `Related → Tasks` list → spec without implementing tasks.
+- **Profile vs install state.** Profile says one set of skills; state file lists another. Surface the divergence and recommend `agentic update` or `agentic profile set <name>`.
+- **Stale state file.** `kitVersion` in state file ≠ currently-running kit. Recommend `agentic update`.
+
+## Step 3 — Prioritize next actions
+
+Rank findings by leverage. Return 3–5 concrete invocations, each as a one-line "do X next" with the slug or path that makes the action unambiguous.
+
+Priority heuristic:
+
+1. **Decisions blocking work.** Proposed ADRs awaiting acceptance, accepted specs without tasks. These unblock everyone downstream.
+2. **Quality gates the profile expects.** `mature` profile + hooks not wired → recommend `/agentic-hooks`. `team` profile + hooks not wired → recommend.
+3. **In-flight work needing review.** Branch ahead of `main` without a fresh-context review → recommend `/agentic-review`.
+4. **Drift / hygiene.** Orphan tasks, state-file staleness, spec ↔ task gaps → recommend `/agentic-audit` or `agentic update`.
+5. **Greenfield gaps.** Missing `AGENTS.md` → `/agentic-bootstrap`. Missing `ARCHITECTURE.md` → `/agentic-architecture` (skip in `poc` and `solo`).
+
+If nothing actionable surfaces, say so explicitly — empty output is real signal, not a gap. Phrase: "No urgent next action. Continue current work or invoke `/agentic-audit` for a full drift check."
+
+## Step 4 — Profile-aware filtering
+
+Apply per-profile rules at the end so the user sees output matched to their maturity:
+
+- **`poc`:** suppress Layer 2 (specs) and Layer 3 (ADRs / tasks) sections entirely if those directories do not exist. Show Layer 1 + Layer 4 only. Recommendation set: `/agentic-ground` for research, `/agentic-audit` for drift, `/agentic-update` for staleness.
+- **`solo`:** Layer 2 / Layer 3 render but ADR / `ARCHITECTURE.md` absence is informational — no "needs action" flag. Specs are universal at this profile; spec-without-tasks remains a real finding.
+- **`team`:** full survey. Default profile.
+- **`mature`:** additionally flag hooks-not-wired louder ("WORKFLOW §11 binding for `mature` profile — `/agentic-hooks` recommended").
+
+## Output contract
+
+A single Markdown message structured as:
+
+```
+## agentic-next
+
+**Profile:** <name> (kit v<X.Y.Z>)
+**Branch:** <name> (<n> commits ahead of main)
+
+### Layer 1 — Constitution
+<one-line status per artifact>
+
+### Layer 2 — Specs (doc/specs/)
+<spec list with status + task count, or "no specs">
+
+### Layer 3 — Plans / Decisions
+<ADR + task summaries with explicit flags>
+
+### Layer 4 — Code
+<branch / tests / hooks / CI status>
+
+### Recommended next (priority)
+1. <action> — <one-line reason>
+2. <action> — <one-line reason>
+...
+```
+
+No file written. No state mutation. Recommendations are advisory; the user decides whether to invoke. Cross-references `agentic-audit` (drift detection), `agentic-update` (kit drift), `agentic-profile` (profile changes) where they apply.
+
+When the host exposes `AskUserQuestion` (per ADR-0014) and the user follows up with a confirmation question after seeing the recommendations, prefer the structured prompt over inline text.

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

@@ -0,0 +1,84 @@
+---
+name: agentic-next
+description: Survey the project's state across the four-layer artifact stack and recommend prioritized next actions, modeled on `flutter doctor`. Use when the user asks "what's next", "next step", "where am I", "project status", "doctor", "what should I do", "audit my workflow". Read-only; complements `agentic-audit` (drift detection, a different question). Profile-aware — `poc` suppresses Layer 2/3 noise, `team`/`mature` run the full survey.
+---
+
+<background_information>
+Read-only state survey + prioritized next-action recommendations. Mirrors `flutter doctor` shape: layer-by-layer status + concrete fix per finding. Complements `agentic-audit` — audit answers "is anything wrong?", next answers "what should I do?".
+
+The skill writes nothing. Output is recommendations the user copies into the next conversation turn or the next CLI invocation.
+
+Codex auto-trigger on description keywords is less mature than Claude Code's. If auto-invocation does not fire when the user asks about workflow status, invoke this skill manually.
+</background_information>
+
+<instructions>
+Step 0 — read state. Detect baseline:
+- Profile + kit version: read `.claude/agentic-state.json` and `.agents/agentic-state.json` if present. Profile defaults to `team` per ADR-0013 when state file missing or no profile field.
+- Filesystem signals: `AGENTS.md` / `CLAUDE.md`, `ARCHITECTURE.md`, `DESIGN.md`, `WORKFLOW.md`, `README.md`, `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod`, `.husky/` / `lefthook.yml` / `.pre-commit-config.yaml`, `.github/workflows/`, current git branch.
+- Per-artifact directories: list `doc/specs/`, `doc/adr/`, `doc/tasks/`. Read each file's frontmatter (`Status:`, `Created:`, `Spec ref:` for tasks) but NOT the full body.
+- Git state: current branch, commits ahead of `main` (`git rev-list --count main..HEAD`), unpushed commits, working-tree dirtiness.
+
+Do not parse skill bodies. Do not run tests. Do not invoke other skills.
+
+Step 1 — layer-by-layer status. Render four sections in this exact order. Use words for status (`present`, `in flight`, `missing`, `stale`) — no emoji.
+
+Layer 1 — Constitution: AGENTS.md / CLAUDE.md, WORKFLOW.md, ARCHITECTURE.md, DESIGN.md (frontend only).
+
+Layer 2 — Specs (doc/specs/): for each file, report Status + count of tasks whose Spec ref points at it. Flag specs with Status: accepted and zero implementing tasks.
+
+Layer 3 — Plans / Decisions: doc/adr/ counts by status, flag proposed ADRs with their slug. doc/tasks/ counts by status, list in-progress + blocked with slug and Spec ref. Flag tasks with no Spec ref and no Board ref as orphans.
+
+Layer 4 — Code: branch + ahead count, tests wired? (npm test / pytest / cargo test / go test), hooks wired? (.husky / lefthook.yml / .pre-commit-config.yaml / .git/hooks/), CI wired? (.github/workflows / .gitlab-ci.yml / .circleci/).
+
+Step 2 — cross-cut signals:
+- Pending fresh-context review: branch ≥1 commits ahead of main with no .agentic/reviews/<ts>-*.md for the current range → recommend agentic-review.
+- Spec ↔ task reciprocity: tasks with non-empty Spec ref whose target spec is missing → orphan; accepted/shipped specs with zero Related → Tasks → spec without implementing tasks.
+- Profile vs install state: profile-declared skill set ≠ on-disk skill set → recommend `agentic update` or `agentic profile set <name>`.
+- Stale state file: kitVersion in state file ≠ currently-running kit → recommend `agentic update`.
+
+Step 3 — prioritize next actions. Rank by leverage. Return 3–5 concrete invocations, each as one-line "do X next" with slug / path.
+
+Priority heuristic:
+1. Decisions blocking work (proposed ADRs, accepted specs without tasks).
+2. Quality gates the profile expects (mature + hooks not wired).
+3. In-flight work needing review (branch ahead without fresh-context review).
+4. Drift / hygiene (orphan tasks, state-file staleness, spec ↔ task gaps).
+5. Greenfield gaps (missing AGENTS.md, missing ARCHITECTURE.md — skip in poc / solo).
+
+If nothing actionable surfaces, say so: "No urgent next action. Continue current work or invoke `/agentic-audit` for a full drift check."
+
+Step 4 — profile-aware filtering. Apply at the end:
+- poc: suppress Layer 2/3 sections if those directories do not exist. Show Layer 1 + Layer 4 only. Recommendation set: `/agentic-ground`, `/agentic-audit`, `agentic update`.
+- solo: Layer 2/3 render; ADR / ARCHITECTURE.md absence is informational, not a flag. Specs are universal; spec-without-tasks remains a real finding.
+- team: full survey (default).
+- mature: additionally flag hooks-not-wired louder (WORKFLOW §11 binding for mature profile).
+</instructions>
+
+<output_contract>
+A single Markdown message structured as:
+
+```
+## agentic-next
+
+**Profile:** <name> (kit v<X.Y.Z>)
+**Branch:** <name> (<n> commits ahead of main)
+
+### Layer 1 — Constitution
+<one-line status per artifact>
+
+### Layer 2 — Specs (doc/specs/)
+<spec list with status + task count, or "no specs">
+
+### Layer 3 — Plans / Decisions
+<ADR + task summaries with explicit flags>
+
+### Layer 4 — Code
+<branch / tests / hooks / CI status>
+
+### Recommended next (priority)
+1. <action> — <one-line reason>
+2. <action> — <one-line reason>
+```
+
+No file written. No state mutation. Recommendations are advisory; the user decides whether to invoke. Cross-references `agentic-audit` (drift detection), `agentic-update` (kit drift), `agentic-profile` (profile changes) where they apply.
+</output_contract>

package/src/skills/codex/agentic-next/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: agentic-next
+  short_description: State-aware navigation aid (flutter doctor pattern). Surveys four-layer artifact stack + recommends prioritized next actions. Read-only.
+policy:
+  allow_implicit_invocation: false