@ara-commons/ara-skills 0.1.0

package/README.md

@@ -0,0 +1,67 @@
+# @ara-commons/ara-skills
+
+One-command installer for the three **Agent-Native Research Artifact (ARA)** skills:
+
+| Skill | Invoke | What it does |
+|-------|--------|--------------|
+| `compiler`         | `/compiler <input>`        | Convert a paper, repo, or notes into a complete ARA artifact |
+| `research-manager` | `/research-manager`        | Post-session recorder that captures decisions, dead ends, and claims |
+| `rigor-reviewer`   | `/rigor-reviewer <dir>`    | ARA Seal Level 2 semantic epistemic review across six dimensions |
+
+## Quick start
+
+```bash
+# interactive (auto-detects Claude Code, Cursor, Gemini CLI, OpenCode, Codex, Hermes)
+npx @ara-commons/ara-skills
+
+# install everything to every detected agent (global / user-level)
+npx @ara-commons/ara-skills install --all
+
+# install just the compiler to Claude Code
+npx @ara-commons/ara-skills install --skill compiler --agent claude-code
+
+# install into the current project instead of $HOME
+npx @ara-commons/ara-skills install --all --local
+```
+
+## Commands
+
+```
+ara-skills                             # interactive
+ara-skills install  [--all] [--skill <id>] [--agent <id>] [--local] [--force]
+ara-skills update   [--agent <id>] [--local]
+ara-skills uninstall [--skill <id>] [--agent <id>] [--local]
+ara-skills list                        # what is installed, where
+ara-skills skills                      # what's available to install
+ara-skills agents                      # which agents are supported / detected
+```
+
+All `--skill` and `--agent` flags are repeatable.
+
+## Agent targets
+
+| Agent        | Global dir                    | Local dir                   |
+|--------------|-------------------------------|-----------------------------|
+| claude-code  | `~/.claude/skills/`           | `.claude/skills/`           |
+| cursor       | `~/.cursor/skills/`           | `.cursor/skills/`           |
+| gemini-cli   | `~/.gemini/skills/`           | `.gemini/skills/`           |
+| opencode     | `~/.opencode/skills/`         | `.opencode/skills/`         |
+| codex        | `~/.codex/skills/`            | `.codex/skills/`            |
+| hermes       | `~/.hermes/skills/`           | `.hermes/skills/`           |
+| generic      | `~/.skills/`                  | `./skills/`                 |
+
+After install, each skill lives at `<target>/<skill-id>/SKILL.md`. A small `.ara-skills.json` lock file records what was installed so `update` and `uninstall --all` work.
+
+## Development
+
+```bash
+cd packages/ara-skills
+npm install
+node bin/cli.js install --skill compiler --local --force
+```
+
+In dev mode the CLI reads skills from the sibling `../../skills/` directory. On `npm pack` / `npm publish`, `prepack` copies that directory into `packages/ara-skills/skills/` so the tarball is self-contained; `postpack` removes the copy afterward.
+
+## Upstream source of truth
+
+The three skill directories live at the repo root under `skills/`. Edit them there — never edit the copy inside this package, which is created on demand by `prepack`.

package/bin/cli.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { main } from '../src/index.js';
+
+main(process.argv.slice(2)).catch((err) => {
+  console.error(`\nError: ${err?.message ?? err}`);
+  if (process.env.ARA_SKILLS_DEBUG) console.error(err?.stack);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@ara-commons/ara-skills",
+  "version": "0.1.0",
+  "description": "Install Agent-Native Research Artifact (ARA) skills — compiler, research-manager, rigor-reviewer — into Claude Code, Cursor, OpenCode, Gemini CLI, Codex, and more.",
+  "type": "module",
+  "bin": {
+    "ara-skills": "./bin/cli.js"
+  },
+  "main": "src/index.js",
+  "scripts": {
+    "start": "node bin/cli.js",
+    "prepack": "node scripts/bundle-skills.mjs",
+    "postpack": "node scripts/clean-bundle.mjs",
+    "test": "node --test test/*.test.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "scripts",
+    "skills",
+    "README.md"
+  ],
+  "keywords": [
+    "ara",
+    "agent-native-research-artifact",
+    "research",
+    "skills",
+    "claude-code",
+    "cursor",
+    "gemini",
+    "opencode",
+    "codex",
+    "compiler",
+    "research-manager",
+    "rigor-reviewer",
+    "llm",
+    "cli"
+  ],
+  "author": "Knowledge Management",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AmberLJC/Agent-Native-Research-Artifact.git",
+    "directory": "packages/ara-skills"
+  },
+  "homepage": "https://github.com/AmberLJC/Agent-Native-Research-Artifact#readme",
+  "bugs": {
+    "url": "https://github.com/AmberLJC/Agent-Native-Research-Artifact/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "chalk": "^5.3.0"
+  }
+}

package/scripts/bundle-skills.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// prepack: copy the monorepo's top-level skills/ into this package so the
+// published tarball is self-contained. Clean-up runs from postpack.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const pkgRoot = path.resolve(here, '..');
+const src = path.resolve(pkgRoot, '..', '..', 'skills');
+const dst = path.join(pkgRoot, 'skills');
+
+if (!fs.existsSync(src)) {
+  console.error(`[ara-skills:prepack] source not found: ${src}`);
+  process.exit(1);
+}
+
+// Don't clobber a bundle that's already inside the package (e.g. user ran
+// `prepack` manually); refresh it anyway for determinism.
+fs.rmSync(dst, { recursive: true, force: true });
+fs.mkdirSync(dst, { recursive: true });
+
+function copyDir(s, d) {
+  fs.mkdirSync(d, { recursive: true });
+  for (const e of fs.readdirSync(s, { withFileTypes: true })) {
+    const a = path.join(s, e.name);
+    const b = path.join(d, e.name);
+    if (e.isDirectory()) copyDir(a, b);
+    else fs.copyFileSync(a, b);
+  }
+}
+
+copyDir(src, dst);
+console.log(`[ara-skills:prepack] bundled skills/ from ${src}`);

package/scripts/clean-bundle.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// postpack: remove the bundled skills/ copy so the working tree stays clean.
+// The published tarball already contains it at this point.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const pkgRoot = path.resolve(here, '..');
+const dst = path.join(pkgRoot, 'skills');
+
+if (fs.existsSync(dst)) {
+  fs.rmSync(dst, { recursive: true, force: true });
+  console.log('[ara-skills:postpack] cleaned packages/ara-skills/skills/');
+}

package/skills/compiler/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: compiler
+description: |
+  Universal ARA Compiler. Converts ANY research input — PDF papers, GitHub repositories,
+  experiment logs, code directories, raw notes, or combinations thereof — into a complete
+  Agent-Native Research Artifact (ARA). Produces a structured, machine-executable knowledge
+  package with cognitive layer (claims, concepts, heuristics), physical layer (configs, code
+  stubs), exploration graph (research DAG), and grounded evidence.
+
+  TRIGGERS: compile, create ARA, generate artifact, convert paper, build artifact, compile paper,
+  ARA from PDF, ARA from repo, ARA from code, structure research, extract knowledge
+argument-hint: "[any input — paths, URLs, descriptions, or nothing]"
+allowed-tools: Read, Write, Edit, Bash(python *|git clone *|ls *|mkdir *), Glob, Grep, Task
+metadata:
+  author: ara-commons
+  category: research-tooling
+  version: "1.0.0"
+  tags: [research, compilation, artifacts, knowledge-extraction]
+---
+
+# Universal ARA Compiler
+
+You are the ARA Universal Compiler. Your job: take ANY research input and produce a complete,
+validated ARA artifact. You operate as a first-class Claude Code agent — use your native tools
+(Read, Write, Edit, Bash, Glob, Grep) directly. No API wrapper needed.
+
+## Input Philosophy
+
+The compiler is **open-ended**. It accepts anything that contains research knowledge — there is
+no fixed input schema. Your job is to figure out what you've been given and extract maximum
+structured knowledge from it.
+
+Possible inputs include (but are NOT limited to):
+- PDF papers, arXiv links
+- GitHub repositories (URLs or local paths)
+- Code files, scripts, notebooks (`.py`, `.ipynb`, `.rs`, `.cpp`, etc.)
+- Experiment logs, training outputs, evaluation results
+- Configuration files, hyperparameter sweeps
+- Raw research notes, brainstorm transcripts, meeting notes
+- Data directories with results, checkpoints, figures
+- Slack/email threads describing research decisions
+- Combinations of the above
+- A verbal description or conversation with the user about their research
+- Nothing at all — the user may want to build an ARA interactively through dialogue
+
+When arguments are provided (`$ARGUMENTS`), interpret them flexibly:
+- File/directory paths → read them
+- URLs → fetch or clone them
+- `--output <dir>` → where to write the ARA (default: `./ara-output/`)
+- `--rubric <path>` → PaperBench rubric for coverage mapping
+- Anything else → treat as context or ask the user for clarification
+
+### Input Reading Strategy
+
+Adapt to whatever you receive:
+1. **Identify what you have.** Glob, read, and explore the provided paths. Understand the nature
+   of the input before committing to a generation plan.
+2. **Maximize coverage.** Cross-reference all available sources. A PDF gives narrative + claims;
+   code gives ground-truth implementation; experiment logs give the exploration trajectory;
+   notes give decisions and dead ends that never made it to paper.
+3. **Ask when stuck.** If the input is ambiguous or incomplete, ask the user to fill gaps rather
+   than hallucinating. The user is a collaborator, not a passive consumer.
+4. **Handle partial inputs gracefully.** Not every ARA field will be fillable from every input.
+   Populate what you can with high confidence, mark gaps explicitly with "Not available from
+   provided input", and tell the user what's missing so they can supplement later.
+
+## Workflow
+
+```
+1. READ all inputs
+2. REASON through the 4-stage epistemic protocol (see below)
+3. GENERATE all ARA files using Write tool
+4. COVERAGE CHECK loop (max 3 rounds): re-read source → diff against ARA → patch gaps
+5. VALIDATE by running Seal Level 1
+6. FIX any failures, re-validate
+7. REPORT summary to user
+```
+
+### Step 1: Read Inputs
+
+Read ALL provided inputs thoroughly before generating anything. For PDFs, read every page,
+**including appendices** — appendices often carry reproduction-critical content and should
+be treated with the same priority as main-text pages.
+
+For repos, prioritize: README → core algorithm files → configs → environment files.
+
+### Step 2: 4-Stage Epistemic Chain-of-Thought
+
+Before writing any files, reason through these 4 stages. Think carefully about each stage.
+
+**Stage 1 — Semantic Deconstruction**
+Strip narrative framing. Extract the raw knowledge atoms:
+- Mathematical formulations and equations
+- Architectural specifications and component descriptions
+- Experimental configurations (hyperparameters, hardware, datasets, seeds)
+- ALL numerical results and benchmarks (exact values, never rounded)
+- Citation dependencies and their roles (imports, extends, bounds, refutes)
+- Negative results, ablation findings, rejected alternatives
+- Implementation tricks, convergence hacks, sensitivity observations
+
+Before moving on, perform an **evidence capture pass**:
+- For every source table or figure you plan to cite, first capture the original source identifier and caption exactly (`Table 2`, `Figure 4`, etc.)
+- Transcribe the raw table/figure content before making any claim-specific summary
+- If you create a filtered view for one claim, store it as a **derived subset**, not as the original table itself
+- Never label a subset or merged summary as `Table N` unless it reproduces the original source table faithfully
+- If PDF extraction is ambiguous, re-read the page with layout preserved or inspect the page manually before writing evidence files
+
+**Stage 2 — Cognitive Mapping**
+Map extracted atoms to `/logic/`:
+- **problem.md**: observations (with numbers) → gaps → key insight → assumptions
+- **claims.md**: falsifiable claims with proof pointers to experiment IDs (E01, E02...), plus a separation between direct evidence basis and higher-level interpretation
+- **concepts.md**: ≥5 formal definitions with notation and boundary conditions
+- **experiments.md**: ≥3 declarative verification plans (NO exact numbers — directional only)
+- **solution/**: architecture (component graph), algorithm (math + pseudocode), constraints, heuristics
+- **related_work.md**: typed dependency graph (imports/extends/bounds/baseline/refutes)
+
+Appendix content (worked examples, prompt templates, enumerated taxonomies, annotation
+schemas, extended analyses, prescriptive content) should be routed into the ARA layers
+where it fits best, preserving the granularity the source uses. Never silently drop an
+appendix section.
+
+When writing claims:
+- Phrase the main `Statement` at the strongest level directly supported by the cited evidence
+- Put raw support in `Evidence basis`
+- Put any broader synthesis in `Interpretation`
+- If the evidence only shows validation metrics, do not upgrade the claim to training dynamics or optimization quality unless training-side evidence is also captured
+
+`related_work.md` should reflect the paper's full citation footprint, not only the
+closest predecessors. Works with a specific technical delta get full `RW` blocks; remaining
+citations from the paper's References list should still be captured (more briefly) so the
+intellectual neighborhood is preserved.
+
+**Stage 3 — Physical Stubbing**
+Generate `/src/`:
+- **configs/**: exact hyperparameter values with rationale and sensitivity
+- **execution/**: ≥1 Python code stub implementing the NOVEL contribution (typed signatures, no boilerplate)
+- **environment.md**: Python version, framework, hardware, dependencies, seeds
+- If repo available: use actual code to improve stub precision
+- If rubric provided: produce `rubric/requirements.md` mapping every leaf node
+
+**Stage 4 — Exploration Graph Extraction**
+Reconstruct the research DAG for `/trace/exploration_tree.yaml`:
+- Root nodes = central research questions
+- Experiments and decisions nest as children
+- Dead ends from ablations/rejected alternatives = typed leaf nodes
+- ≥8 nodes, must include dead_end and decision types
+- Use `also_depends_on` for DAG convergence points
+- Every node must declare whether it is `explicit` from source material or `inferred` from reconstruction
+- Explicit nodes should carry source references (table/figure/section labels)
+- Inferred nodes are allowed only when they help reconstruct the paper's logic without pretending to be literal session logs
+
+### Step 3: Generate Files
+
+Write ALL mandatory files. See `${CLAUDE_SKILL_DIR}/references/ara-schema.md` for the complete
+directory structure and field-level requirements for every file.
+
+**Mandatory files** (all must exist and be non-trivial):
+- `PAPER.md` — YAML frontmatter (title, authors, year, venue, doi, ara_version, domain, keywords, claims_summary, abstract) + Layer Index
+- `logic/problem.md` — Observations (O1, O2...), Gaps (G1, G2...), Key Insight, Assumptions
+- `logic/claims.md` — Claims (C01, C02...) each with Statement, Status, Falsification criteria, Proof, Evidence basis, Interpretation, Dependencies, Tags
+- `logic/concepts.md` — ≥5 concepts each with Notation, Definition, Boundary conditions, Related concepts
+- `logic/experiments.md` — ≥3 experiments (E01, E02...) each with Verifies, Setup, Procedure, Metrics, Expected outcome (directional only!), Baselines, Dependencies
+- `logic/solution/architecture.md` — Component graph with inputs/outputs
+- `logic/solution/algorithm.md` — Math formulation + pseudocode + complexity
+- `logic/solution/constraints.md` — Boundary conditions and limitations
+- `logic/solution/heuristics.md` — Heuristics (H01, H02...) each with Rationale, Sensitivity, Bounds, Code ref, Source
+- `logic/related_work.md` — Related work (RW01, RW02...) each with DOI, Type, Delta, Claims affected
+- `src/configs/training.md` — Hyperparameters with Value, Rationale, Search range, Sensitivity, Source
+- `src/configs/model.md` — Model/architecture configs
+- `src/execution/{module}.py` — ≥1 code stub with typed signatures
+- `src/environment.md` — Python version, framework, hardware, dependencies, seeds
+- `trace/exploration_tree.yaml` — Research DAG (≥8 nodes, nested YAML)
+- `evidence/README.md` — Index table mapping every evidence file to claims
+- `evidence/tables/*.md` — ALL result tables (exact cell values, never rounded)
+- `evidence/figures/*.md` — ALL quantitative figures (extracted data points)
+
+Evidence-generation rules:
+- Preserve **raw source tables** separately from any **derived subset** views
+- A file named after a source object (for example `table3_...`) must match that source object's caption and contents
+- If only a subset is included, the filename must say `derived_`, `subset_`, or equivalent, and the file must state what it was derived from
+- Do not merge rows from different source tables into one evidence file unless the file is explicitly labeled as a derived comparison
+
+### Step 4: Coverage Check Loop (max 3 rounds)
+
+Before running Seal validation, verify that the ARA faithfully covers the source material.
+Repeat up to **3 rounds**; stop early if a round produces no patches.
+
+**Each round:** re-read the source, identify anything not yet captured or only shallowly
+captured in the ARA, patch those gaps, then note how many fixes were made. If zero, exit
+early. Pay particular attention to appendix content and to citations from the paper's
+References list, which are easy to miss on the first pass.
+
+The coverage loop does not replace validation — it ensures the ARA is semantically complete
+before structural checks run.
+
+### Step 5: Validate
+
+Run ARA Seal Level 1 validation. Perform these checks:
+- All mandatory dirs exist: `logic/`, `logic/solution/`, `src/`, `src/configs/`, `trace/`, `evidence/`
+- All mandatory files exist and are non-empty
+- PAPER.md has YAML frontmatter with title, authors, year
+- PAPER.md has Layer Index section
+- claims.md has C01+ blocks with Statement, Status, Falsification criteria, Proof fields
+- experiments.md has E01+ blocks with Verifies, Setup, Procedure, Expected outcome fields
+- heuristics.md has H01+ blocks with Rationale, Sensitivity, Bounds fields
+- concepts.md has ≥5 concept sections
+- experiments.md has ≥3 experiment plans
+- exploration_tree.yaml parses as valid YAML with ≥8 nodes, has dead_end and decision types
+- Claim Proof references (E01, E02...) resolve to experiments.md
+- Experiment Verifies references (C01, C02...) resolve to claims.md
+- Heuristic Code ref paths resolve to actual files in src/execution/
+- Evidence files contain Markdown tables with **Source** fields
+- Evidence file names, source labels, and captions agree on the original table/figure identifier
+- Any file named like a raw source table is a faithful transcription rather than a filtered subset
+- Claims only cite experiments whose evidence actually contains the compared rows or measurements
+- Claim wording does not outrun the evidence type (for example, validation tables alone should not be used to claim training-dynamics improvements)
+- Trace nodes declare `support_level: explicit|inferred`
+- Trace nodes with `support_level: explicit` include source references
+
+### Step 6: Fix & Iterate
+
+For each validation failure:
+1. Read the failing file
+2. Apply targeted edits (prefer Edit over full rewrite to preserve correct content)
+3. Re-validate after all fixes
+
+Typically converges in 2-3 rounds.
+
+### Step 7: Report
+
+Print a summary:
+- Artifact location
+- File count and total size
+- Validation result (pass/fail with details)
+- Key statistics: number of claims, experiments, heuristics, concepts, tree nodes, evidence files
+
+## Critical Rules
+
+1. **Exact numbers**: All numerical values copied EXACTLY from source — never round or approximate
+2. **No hallucination**: Never invent claims, results, or heuristics not in the source material
+3. **Experiments have NO exact numbers**: `experiments.md` contains only directional/relative expected outcomes. Exact numbers go in `evidence/`
+4. **Every claim has proof**: Proof field references experiment IDs (E01, E02), not file paths
+5. **Cross-layer binding**: Claims ↔ Experiments ↔ Evidence ↔ Code refs must all resolve
+6. **Dead ends matter**: Include failed approaches, rejected alternatives, ablation findings
+7. **"Not specified"**: If information is genuinely unavailable, write "Not specified in paper" — never guess
+8. **No fake source labels**: Never call a derived subset `Table N` or `Figure N` unless it faithfully reproduces the original source object
+9. **No synthetic trace history**: Do not invent decisions, dead ends, or experiments that are not explicit in the provided inputs; if a trajectory is inferred, mark it as inferred or omit it
+10. **Evidence-limited wording**: Do not use stronger language than the evidence supports; separate direct observations from interpretation
+
+## Reference Files
+
+For detailed schema specifications, load these on demand:
+- `${CLAUDE_SKILL_DIR}/references/ara-schema.md` — Complete ARA directory schema with field-level format for every file
+- `${CLAUDE_SKILL_DIR}/references/exploration-tree-spec.md` — Detailed exploration tree YAML specification with examples
+- `${CLAUDE_SKILL_DIR}/references/validation-checklist.md` — All Seal Level 1 checks (what the validator looks for)