@alexandrealvaro/agentic 0.3.0-beta.2 → 0.4.0-beta.1

package/README.md

@@ -35,6 +35,7 @@ Two categories ([ADR-0007](doc/adr/0007-workflow-operational-skills.md)) and two
 | `agentic-audit` | spec-driven | universal | Read-only drift report (AGENTS.md / ARCHITECTURE.md / ADRs) | `/agentic-audit` |
 | `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-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` |
@@ -119,6 +120,8 @@ Prompts reference templates by relative path. Two ways to give your agent access
 
 **Reviewing your own diff.** Run `/agentic-review <range>` (e.g. `/agentic-review main..HEAD` or `/agentic-review PR#42`). The skill assembles the diff, the relevant spec slice (`AGENTS.md`, applicable ADRs, the task's Acceptance Criteria), and delegates to a fresh-context reviewer subagent — no inherited bias from the session that wrote the code (WORKFLOW §10). Returns structured findings grouped Blocker / Concern / Note. Codex variant uses `/clear` + paste handoff since Codex has no subagent primitive.
 
+**Researching before implementation.** Run `/agentic-ground` (or let it auto-trigger on non-trivial work). The skill runs a four-source levantamento — official docs, validated open-source examples, in-repo patterns, and git history — synthesizes a happy path with citations from each source, and gates any deviation behind an irrefutable justification before code is written (WORKFLOW §4 + §5). Output is the input to whatever produces the implementation plan; the skill does not write code.
+
 **Project already built with agents.** Treat missing artifacts as brownfield (run the relevant skill) and existing artifacts as audit (`/agentic-audit`).
 
 ## What ends up in your target project

package/WORKFLOW.md

@@ -89,6 +89,8 @@ Then check continuously, especially mid-implementation:
 
 Sometimes you can't follow the happy path — that's fine. But always know where it is and why you left it.
 
+The kit ships `agentic-ground` (workflow-operational skill) as the bound implementation of §4 + §5: it runs a four-source research pass (official docs, validated open-source examples, in-repo patterns, git history), synthesizes the happy path with citations, and gates any deviation behind an irrefutable justification before code is written.
+
 ## 5. Ground in Real Patterns
 
 Don't dump the codebase into context. Anchor the model in a specific, project-relevant example.
@@ -97,6 +99,8 @@ Don't dump the codebase into context. Anchor the model in a specific, project-re
 
 Cite specific files, not "the codebase." Use just-in-time retrieval: pass paths or IDs and let the agent fetch via tools when it needs to read them.
 
+`agentic-ground` (see §4) is the workflow-operational skill that combines this with the other three research sources — official docs, validated OSS, and git history — into one indivisible pre-implementation pass.
+
 ## 6. Explore → Plan → Implement → Commit
 
 For non-trivial changes, four phases:

package/package.json

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

@@ -51,6 +51,7 @@ export const REQUIRED_SKILLS = [
   'agentic-task',
   'agentic-audit',
   'agentic-review',
+  'agentic-ground',
 ];
 
 /**
@@ -266,6 +267,7 @@ export async function initCommand(opts) {
       '/agentic-task',
       '/agentic-audit',
       '/agentic-review (WORKFLOW §10)',
+      '/agentic-ground (WORKFLOW §4 + §5)',
       ...(optedSkills.includes('agentic-design') ? ['/agentic-design (DESIGN.md)'] : []),
       ...(optedSkills.includes('agentic-subagent') && agents.includes('claude-code')
         ? ['/agentic-subagent']

package/src/lib/rootdoc.js

@@ -22,6 +22,8 @@ export const SKILL_DESCRIPTIONS = {
     'Read-only drift report comparing AGENTS.md / ARCHITECTURE.md / ADRs against the code.',
   'agentic-review':
     '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-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-ground/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: agentic-ground
+description: Four-source pre-implementation research — official docs, validated open-source examples, in-repo patterns, and git history — then synthesize a happy path and gate any deviation with an irrefutable justification before code is written. Auto-invokes on non-trivial work, refactors, library or pattern selection, "research before coding", "before implementing", "which library", "which pattern", "how to approach", "ground before coding". Workflow-operational counterpart to WORKFLOW.md §4 (Find the Happy Path) and §5 (Ground in Real Patterns); pairs with agentic-philosophy (posture) and agentic-review (post-implementation §10 review).
+allowed-tools: Read, Glob, Grep, Bash, WebFetch, WebSearch
+---
+
+# /agentic-ground
+
+Implements WORKFLOW §4 + §5 end-to-end as a single research pass. The four sources are joined by **AND**, not OR — every non-trivial change runs the full levantamento, then synthesizes a happy path, then justifies any deviation. Output is the input to whatever skill or freeform turn produces the implementation plan; this skill does not write code.
+
+## Step 0 — Scope the recortte
+
+Confirm what is being researched. The recortte is the smallest verifiable surface that captures the change: a function to add, a library to pick, a pattern to apply. State it in one sentence before research starts. If the surface is broader than one sentence captures, ask the user to narrow it; broad recorttes produce diluted research.
+
+If the change is genuinely trivial (rename, typo, one-line refactor on a tested path), skip this skill.
+
+## Step 1 — Four-source levantamento (all four required)
+
+### Source A — official documentation
+
+For each language and library in scope, cite the canonical doc URL and version. Use `WebFetch` to confirm the page exists and read the relevant section; use `WebSearch` to locate it if the URL is unknown. If neither produces a confident hit, ask the user for a known-good link rather than fabricating one. Output: bulleted citations, one per language/library, each with URL plus a one-line summary of the relevant guidance.
+
+### Source B — validated open-source examples
+
+Find ≥1 (prefer 2–3) public repository solving the same *technical* recortte with similar techniques. The match is technical, not domain — a CRUD-app-with-auth and a CLI-with-auth both hit "auth flow", and either is valid for the auth recortte. Use `WebSearch` (e.g. `site:github.com <recortte> language:<lang>`) and follow up with `WebFetch` of the specific file. Cite `<repo>:<path>:<line-range>` and quote the relevant block — never paraphrase code from training memory. If search is inconclusive, ask the user for a known reference.
+
+### Source C — in-repo examples
+
+Grep / glob the current repo for analogous patterns. Cite `<file>:<line>` plus a one-line description of how the existing example handles the same shape. If the codebase has no analog, state that explicitly (real signal, not a gap).
+
+### Source D — git history
+
+Run `git log --all --oneline -- <relevant-paths>`, `git log --all --grep=<keyword>`, and a sweep of sibling active branches (`git branch -a`, then `git log <branch> -- <paths>` on those that look related). Surface any prior attempt or sibling solution — including abandoned ones — with `<commit-sha>` plus the touching file path and a one-line description. If the search is genuinely empty, state "no prior attempt found" — that is the valid Source D outcome when there isn't one. Narrow with `--grep` or `-S` on multi-thousand-commit repos.
+
+## Step 2 — Happy path synthesis
+
+In one paragraph, name the most-grounded approach for the recortte and cite at least one source per Source A / B / C. Source D is included when it produced a hit; otherwise mark "no prior attempt found." The paragraph is the canonical answer the engineer would give if asked "what is the canonical, idiomatic way to solve this here?" — the question WORKFLOW.md §4 frames.
+
+## Step 3 — Deviation gate
+
+If the implementation the user (or you) is about to write deviates from the synthesized happy path, write the justification before any code lands. The justification must name the specific constraint, evidence, or trade-off forcing the deviation — generic "we want it differently" is insufficient. If the justification cannot be written confidently, loop back to Step 1 and look harder; do not deviate without it.
+
+The gate is prescriptive, not descriptive: WORKFLOW §4 asks "was the deviation deliberate?"; this gate asks "is the deviation defensible against the four sources?" Write the answer down.
+
+## Step 4 — Confidence checkpoint
+
+Before handing off to implementation, report a soft verdict against four checks:
+
+- A consulted (≥1 official-doc citation per language/library)
+- B consulted (≥1 OSS citation, with cite-and-fetched code)
+- C consulted (in-repo analog cited or "no analog found" stated)
+- D checked (commits / branches surveyed; hit cited or "no prior attempt found")
+- Happy path declared (Step 2)
+- Deviation, if any, justified (Step 3)
+
+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.
+
+## Output contract
+
+A single message structured as:
+
+```
+## Recortte
+<one sentence>
+
+## Source A — official documentation
+- <lang/lib>: <URL@version> — <one-line summary>
+
+## Source B — validated open-source examples
+- <repo>:<path>:<line-range> — <one-line summary>
+  ```
+  <quoted code block>
+  ```
+
+## Source C — in-repo examples
+- <file>:<line> — <one-line summary>
+- (or: "no analog found in the codebase")
+
+## Source D — git history
+- <commit-sha> <touching-path> — <one-line summary>
+- (or: "no prior attempt found")
+
+## Happy path
+<one paragraph synthesizing A + B + C + D, with citations>
+
+## Proposed implementation vs happy path
+- aligned: <what stays canonical>
+- deviates: <list of deviations>
+  - <deviation>: <irrefutable justification>
+
+## Confidence checkpoint
+- A consulted: yes / no — <gap if no>
+- B consulted: yes / no — <gap if no>
+- C consulted: yes / no — <gap if no>
+- D checked: yes / no — <gap if no>
+- happy path declared: yes
+- deviations justified: yes / no / n.a.
+```
+
+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).

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

@@ -0,0 +1,82 @@
+---
+name: agentic-ground
+description: Four-source pre-implementation research — official docs, validated open-source examples, in-repo patterns, and git history — then synthesize a happy path and gate any deviation with an irrefutable justification before code is written. Auto-invokes on non-trivial work, refactors, library or pattern selection, "research before coding", "before implementing", "which library", "which pattern", "how to approach", "ground before coding". Workflow-operational counterpart to WORKFLOW.md §4 (Find the Happy Path) and §5 (Ground in Real Patterns).
+---
+
+<background_information>
+Implements WORKFLOW §4 + §5 end-to-end as one research pass. The four sources are joined by AND, not OR — every non-trivial change runs the full levantamento, then synthesizes a happy path, then justifies any deviation. Output is the input to whatever skill or freeform turn produces the implementation plan; this skill does not write code.
+
+Codex auto-trigger on description keywords is less mature than Claude Code's. If auto-invocation does not fire on a non-trivial change, invoke this skill manually before implementing.
+</background_information>
+
+<instructions>
+Step 0 — scope the recortte. Confirm what is being researched in one sentence. The recortte is the smallest verifiable surface that captures the change: a function to add, a library to pick, a pattern to apply. If broader than one sentence, ask the user to narrow. Skip the skill on genuinely trivial diffs (rename, typo, one-line refactor on a tested path).
+
+Step 1 — four-source levantamento, all four required:
+
+Source A — official documentation. For each language and library in scope, cite the canonical doc URL and version. Read the relevant section. Ask the user for a known-good link rather than fabricating one. Output: bulleted citations, one per language/library, each with URL plus a one-line summary.
+
+Source B — validated open-source examples. ≥1 (prefer 2–3) public repository solving the same technical recortte with similar techniques. Match is technical, not domain. Cite `<repo>:<path>:<line-range>` and quote the relevant block — never paraphrase from training memory. If search is inconclusive, ask the user for a known reference.
+
+Source C — in-repo examples. Grep / glob for analogous patterns. Cite `<file>:<line>` plus a one-line description of how the existing example handles the same shape. If the codebase has no analog, state that explicitly.
+
+Source D — git history. Run `git log --all --oneline -- <relevant-paths>`, `git log --all --grep=<keyword>`, sweep sibling active branches. Cite `<commit-sha>` plus touching file path and a one-line description. If empty, state "no prior attempt found." Narrow with `--grep` or `-S` on multi-thousand-commit repos.
+
+Step 2 — happy path synthesis. In one paragraph, name the most-grounded approach for the recortte and cite at least one source per Source A / B / C. Source D included when it produced a hit; otherwise mark "no prior attempt found." The paragraph is the canonical answer to "what is the canonical, idiomatic way to solve this here?"
+
+Step 3 — deviation gate. If the implementation about to be written deviates from the happy path, write the justification first. Must name the specific constraint, evidence, or trade-off forcing the deviation — generic "we want it differently" is insufficient. If the justification cannot be written confidently, loop back to Step 1 and look harder; do not deviate without it. Prescriptive gate, not descriptive — write the answer down.
+
+Step 4 — confidence checkpoint. Soft verdict on:
+- A consulted (≥1 official-doc citation per language/library)
+- B consulted (≥1 OSS citation, with cite-and-fetched code)
+- C consulted (in-repo analog cited or "no analog found" stated)
+- D checked (commits / branches surveyed; hit cited or "no prior attempt found")
+- Happy path declared (Step 2)
+- Deviation, if any, justified (Step 3)
+
+If any check fails, surface the gap to the user and ask before proceeding. Do not block. The user retains authority to skip; the discipline is in surfacing.
+</instructions>
+
+<output_contract>
+A single message structured as:
+
+```
+## Recortte
+<one sentence>
+
+## Source A — official documentation
+- <lang/lib>: <URL@version> — <one-line summary>
+
+## Source B — validated open-source examples
+- <repo>:<path>:<line-range> — <one-line summary>
+  ```
+  <quoted code block>
+  ```
+
+## Source C — in-repo examples
+- <file>:<line> — <one-line summary>
+- (or: "no analog found in the codebase")
+
+## Source D — git history
+- <commit-sha> <touching-path> — <one-line summary>
+- (or: "no prior attempt found")
+
+## Happy path
+<one paragraph synthesizing A + B + C + D, with citations>
+
+## Proposed implementation vs happy path
+- aligned: <what stays canonical>
+- deviates: <list of deviations>
+  - <deviation>: <irrefutable justification>
+
+## Confidence checkpoint
+- A consulted: yes / no — <gap if no>
+- B consulted: yes / no — <gap if no>
+- C consulted: yes / no — <gap if no>
+- D checked: yes / no — <gap if no>
+- happy path declared: yes
+- deviations justified: yes / no / n.a.
+```
+
+No code is written by this skill. The output feeds the next turn or another skill.
+</output_contract>

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

@@ -0,0 +1,5 @@
+interface:
+  display_name: agentic-ground
+  short_description: Four-source pre-implementation research (docs / OSS / in-repo / git history) plus happy-path synthesis and deviation gate. WORKFLOW §4 + §5.
+policy:
+  allow_implicit_invocation: false