@alexandrealvaro/agentic 0.9.3-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.3-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

@@ -48,6 +48,7 @@ const ROOT_DOC_LABEL = {
   updated: '~ ',
   unchanged: '· ',
   skipped: '! ',
+  'kept-stale': '! ',
   absent: '',
 };
 
@@ -339,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/commands/update.js

@@ -47,6 +47,7 @@ const ACTION_SYMBOL = {
   kept: '·',
   skipped: '!',
   removed: '-',
+  'removed-missing': '?',
   'orphan-kept': '?',
 };
 
@@ -55,6 +56,7 @@ const ROOT_DOC_LABEL = {
   updated: '~ ',
   unchanged: '· ',
   skipped: '! ',
+  'kept-stale': '! ',
   absent: '',
 };
 
@@ -86,13 +88,24 @@ function skillsForAgent(agent, profileName, optedSkills) {
   return [...universal, ...conditional];
 }
 
-function previousAgentsFromStates(cwd) {
-  const out = [];
+/**
+ * Load every per-agent state file once. Returns `{ statesByAgent, agents }`
+ * where `agents` lists the agents whose state files exist on disk. Avoids
+ * the prior pattern of calling `loadState` twice per agent (once for
+ * presence detection, once for content); also surfaces malformed-state
+ * errors with the loader's own context, in a single pass.
+ */
+function loadStatesOnce(cwd) {
+  const statesByAgent = {};
+  const agents = [];
   for (const agent of VALID_AGENTS) {
     const state = loadState(cwd, agent);
-    if (state) out.push(agent);
+    if (state) {
+      statesByAgent[agent] = state;
+      agents.push(agent);
+    }
   }
-  return out;
+  return { statesByAgent, agents };
 }
 
 function previouslyOptedConditional(previousStates, currentAgents, profileName) {
@@ -140,18 +153,23 @@ export async function updateCommand(opts) {
   }
 
   const cwd = process.cwd();
-  const interactive = process.stdout.isTTY && !opts.yes && !opts.agent;
+  // `--agent` is purely a narrowing flag and does not imply non-interactive
+  // intent. Only `--yes` or a non-TTY shell suppress the TUI per ADR-0009.
+  const interactive = process.stdout.isTTY && !opts.yes;
   const dryRun = Boolean(opts.dryRun);
   const force = Boolean(opts.force);
 
   const detectedAgents = detectAgents(cwd);
   const features = detectFeatures(cwd);
-  const previousAgents = previousAgentsFromStates(cwd);
+  const { statesByAgent, agents: previousAgents } = loadStatesOnce(cwd);
 
   const agents = resolveAgents(opts.agent, detectedAgents, previousAgents);
+  // previousStates is the per-agent slice of statesByAgent restricted to the
+  // agents the current invocation targets. Agents outside the slice keep
+  // their state file untouched on disk.
   const previousStates = {};
   for (const agent of agents) {
-    previousStates[agent] = loadState(cwd, agent);
+    previousStates[agent] = statesByAgent[agent] ?? null;
   }
 
   const profileName = profileFromStates(previousStates, agents);
@@ -282,13 +300,24 @@ export async function updateCommand(opts) {
       }
     : async () => true;
 
-  const rootDocAction = !dryRun
-    ? await updateRootDoc({
-        cwd,
-        skills: skillDisplayOrder,
-        confirmAppend,
-      })
-    : { type: 'absent', path: null };
+  const confirmRootDocReplace = interactive
+    ? async (path) => {
+        const answer = await p.confirm({
+          message: `${path}: managed section diverged on disk. Regenerate it? (any edits between the agentic-managed-skills markers will be lost)`,
+          initialValue: false,
+        });
+        if (p.isCancel(answer)) return false;
+        return answer;
+      }
+    : async () => Boolean(force);
+
+  const rootDocAction = await updateRootDoc({
+    cwd,
+    skills: skillDisplayOrder,
+    confirmAppend,
+    confirmReplace: confirmRootDocReplace,
+    dryRun,
+  });
 
   const lines = allActions.map((a) => {
     const sym = ACTION_SYMBOL[a.type] ?? '?';

package/src/lib/install.js

@@ -356,7 +356,16 @@ export async function removeOrphanSkills({
 
     for (const f of entry.files) {
       const abs = join(cwd, f.path);
-      if (existsSync(abs) && !dryRun) {
+      if (!existsSync(abs)) {
+        // State recorded the file at install time but it is gone on disk
+        // now (manually deleted, moved, or never written). Surface as a
+        // distinct action so the user sees the state-vs-reality mismatch
+        // instead of a silent "removed" line for a file that was never
+        // there.
+        actions.push({ type: 'removed-missing', path: f.path, agent });
+        continue;
+      }
+      if (!dryRun) {
         unlinkSync(abs);
       }
       actions.push({ type: 'removed', path: f.path, agent });

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.',
@@ -93,18 +95,23 @@ function replaceSection(body, newSection, bounds) {
  * Behaviour:
  *   - No root doc → returns { type: 'absent', path: null }. Skill bootstraps create the file later.
  *   - Section already present and matches → { type: 'unchanged', path }.
- *   - Section already present and stale → updated in place → { type: 'updated', path }.
+ *   - Section already present and stale → confirmReplace(path) is called; on true → updated → { type: 'updated', path }; on false → { type: 'kept-stale', path } (managed-section diverged on disk and the user chose to keep it).
  *   - Section absent → confirmAppend(path) is called; on true → appended → { type: 'appended', path }; on false → { type: 'skipped', path }.
+ *   - dryRun true → no writes; returned `type` reflects what *would* happen.
  *
  * @param {object} opts
  * @param {string} opts.cwd  Target project root.
  * @param {string[]} opts.skills  Skill names actually installed (in display order).
  * @param {(path: string) => Promise<boolean>} [opts.confirmAppend]  Async confirmation callback for the append-to-existing-file case. Default: skip.
+ * @param {(path: string) => Promise<boolean>} [opts.confirmReplace]  Async confirmation callback for the replace-existing-section case (managed section present on disk but stale). Default: replace (preserves the v0.5 behaviour where update silently regenerates the managed block on every kit / skill change). Wire to a prompt to honor user edits between markers.
+ * @param {boolean} [opts.dryRun]  When true, computes the action without writing.
  */
 export async function updateRootDoc({
   cwd,
   skills,
   confirmAppend = async () => false,
+  confirmReplace = async () => true,
+  dryRun = false,
 }) {
   const found = findRootDoc(cwd);
   if (!found) return { type: 'absent', path: null };
@@ -116,7 +123,9 @@ export async function updateRootDoc({
   if (bounds) {
     const updated = replaceSection(body, section, bounds);
     if (updated === body) return { type: 'unchanged', path: found.name };
-    writeFileSync(found.path, updated);
+    const ok = await confirmReplace(found.name);
+    if (!ok) return { type: 'kept-stale', path: found.name };
+    if (!dryRun) writeFileSync(found.path, updated);
     return { type: 'updated', path: found.name };
   }
 
@@ -124,6 +133,6 @@ export async function updateRootDoc({
   if (!ok) return { type: 'skipped', path: found.name };
 
   const sep = body.endsWith('\n') ? '\n' : '\n\n';
-  writeFileSync(found.path, body + sep + section + '\n');
+  if (!dryRun) writeFileSync(found.path, body + sep + section + '\n');
   return { type: 'appended', path: found.name };
 }

package/src/lib/state.js

@@ -77,9 +77,22 @@ export function saveState(cwd, agent, state) {
 }
 
 function orderState(state) {
+  if (!state || typeof state !== 'object') {
+    throw new Error('orderState: state must be an object');
+  }
+  if (!state.skills || typeof state.skills !== 'object') {
+    throw new Error(
+      'orderState: state.skills must be an object (got ' + typeof state.skills + ')'
+    );
+  }
   const skills = {};
   for (const skillName of Object.keys(state.skills).sort()) {
     const entry = state.skills[skillName];
+    if (!entry || !Array.isArray(entry.files)) {
+      throw new Error(
+        `orderState: state.skills["${skillName}"].files must be an array`
+      );
+    }
     const files = [...entry.files].sort((a, b) => a.path.localeCompare(b.path));
     skills[skillName] = {
       version: entry.version,

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