create-agentic-repo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 create-agentic-repo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# create-agentic-repo
+
+Scaffold a context-lean **Agentic Repo Harness v2** workspace for Claude, Codex, and Antigravity.
+
+## Install
+
+```bash
+npm i -g create-agentic-repo
+```
+
+Or run directly:
+
+```bash
+npx create-agentic-repo my-project --template minimal --yes
+```
+
+## Usage
+
+```bash
+create-agentic-repo <name> [options]
+```
+
+### Options
+
+- `--template minimal` Template to use (only `minimal` for now).
+- `--yes` Non-interactive mode. If `<name>` is omitted, defaults to `agentic-repo`.
+- `--no-git` Skip `git init` in the generated project.
+- `--dry-run` Show actions without writing files.
+- `-h, --help` Show help.
+
+## What it generates
+
+`minimal` creates a harness-first tree:
+
+- `00_inbox/` rich raw context drop zone
+- `01_harness/` always-on lean rules/taskflow
+- `02_context/` distilled 5-minute context
+- `03_specs/` one active spec + backlog/decisions
+- `04_outputs/`, `05_scratch/`
+- `shared/skills/` on-demand skills (includes vendored `skill-creator`)
+- `shared/agents/` role agents (one folder per agent)
+- `runners/` adapters for Claude/Codex/Antigravity
+
+## Development
+
+```bash
+npm run smoke
+```
+
+The smoke test scaffolds a temp project, verifies critical files, validates placeholder replacement, and checks `--dry-run` behavior.

package/bin/create-agentic-repo.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+const { main } = require('../lib/cli');
+
+main();

package/lib/cli.js

@@ -0,0 +1,139 @@
+const path = require('node:path');
+const { scaffoldProject } = require('./scaffold');
+
+function printHelp() {
+  console.log('create-agentic-repo');
+  console.log('');
+  console.log('Usage:');
+  console.log('  create-agentic-repo <name> [options]');
+  console.log('');
+  console.log('Options:');
+  console.log('  --template <name>   Template to use (default: minimal)');
+  console.log('  --yes               Non-interactive mode');
+  console.log('  --no-git            Skip git init in generated project');
+  console.log('  --dry-run           Show actions without creating files');
+  console.log('  -h, --help          Show help');
+}
+
+function parseArgs(argv) {
+  let name;
+  let template = 'minimal';
+  let yes = false;
+  let noGit = false;
+  let dryRun = false;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+
+    if (arg === '-h' || arg === '--help') {
+      return { help: true };
+    }
+
+    if (arg === '--yes') {
+      yes = true;
+      continue;
+    }
+
+    if (arg === '--no-git') {
+      noGit = true;
+      continue;
+    }
+
+    if (arg === '--dry-run') {
+      dryRun = true;
+      continue;
+    }
+
+    if (arg === '--template') {
+      template = argv[i + 1];
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--template=')) {
+      template = arg.slice('--template='.length);
+      continue;
+    }
+
+    if (arg.startsWith('-')) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+
+    if (!name) {
+      name = arg;
+      continue;
+    }
+
+    throw new Error(`Unexpected argument: ${arg}`);
+  }
+
+  if (!name && yes) {
+    name = 'agentic-repo';
+  }
+
+  if (!name) {
+    throw new Error('Project name is required (or pass --yes to use default name).');
+  }
+
+  if (template !== 'minimal') {
+    throw new Error(`Unsupported template: ${template}. Only "minimal" is available.`);
+  }
+
+  return {
+    dryRun,
+    help: false,
+    name,
+    noGit,
+    template,
+    yes,
+  };
+}
+
+function printNextSteps(projectName) {
+  console.log('');
+  console.log('Next steps:');
+  console.log(`1) cd ${projectName}`);
+  console.log('2) Drop your raw context into 00_inbox/');
+  console.log('3) Run Distill using 01_harness/TASKFLOW.md');
+}
+
+function main() {
+  try {
+    const parsed = parseArgs(process.argv.slice(2));
+    if (parsed.help) {
+      printHelp();
+      return;
+    }
+
+    const projectName = parsed.name;
+    const targetDir = path.resolve(process.cwd(), projectName);
+    const logger = (line) => console.log(line);
+
+    scaffoldProject({
+      dryRun: parsed.dryRun,
+      logger,
+      noGit: parsed.noGit,
+      projectName,
+      targetDir,
+      template: parsed.template,
+    });
+
+    if (parsed.dryRun) {
+      console.log('');
+      console.log('Dry run complete. No files were written.');
+      return;
+    }
+
+    console.log('');
+    console.log(`Created ${projectName}.`);
+    printNextSteps(projectName);
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exitCode = 1;
+  }
+}
+
+module.exports = {
+  main,
+  parseArgs,
+};

package/lib/fs-utils.js

@@ -0,0 +1,119 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+function pathExists(targetPath) {
+  try {
+    fs.accessSync(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isDirectoryEmpty(dirPath) {
+  return fs.readdirSync(dirPath).length === 0;
+}
+
+function copyDirectoryRecursive(srcDir, destDir, options) {
+  const { dryRun, logger } = options;
+
+  if (!dryRun) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+  logger(`[copy] ${destDir}`);
+
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirectoryRecursive(srcPath, destPath, options);
+      continue;
+    }
+
+    if (entry.isFile()) {
+      logger(`[copy] ${destPath}`);
+      if (!dryRun) {
+        fs.copyFileSync(srcPath, destPath);
+        const srcMode = fs.statSync(srcPath).mode;
+        fs.chmodSync(destPath, srcMode);
+      }
+    }
+  }
+}
+
+function replacePlaceholdersInTextFiles(rootDir, replacements, options) {
+  const { dryRun, logger } = options;
+  const textExtensions = new Set(['.md', '.txt']);
+
+  function walk(currentDir) {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const filePath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        walk(filePath);
+        continue;
+      }
+
+      if (!entry.isFile()) {
+        continue;
+      }
+
+      const ext = path.extname(filePath).toLowerCase();
+      if (!textExtensions.has(ext)) {
+        continue;
+      }
+
+      const original = fs.readFileSync(filePath, 'utf8');
+      let next = original;
+
+      for (const [token, value] of Object.entries(replacements)) {
+        next = next.split(token).join(value);
+      }
+
+      if (next !== original) {
+        logger(`[replace] ${filePath}`);
+        if (!dryRun) {
+          fs.writeFileSync(filePath, next, 'utf8');
+        }
+      }
+    }
+  }
+
+  walk(rootDir);
+}
+
+function ensureKeepFilesForEmptyDirs(rootDir, options) {
+  const { dryRun, logger } = options;
+
+  function visit(currentDir) {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        visit(path.join(currentDir, entry.name));
+      }
+    }
+
+    const remaining = fs.readdirSync(currentDir);
+    if (remaining.length === 0) {
+      const keepPath = path.join(currentDir, '.keep');
+      logger(`[keep] ${keepPath}`);
+      if (!dryRun) {
+        fs.writeFileSync(keepPath, '', 'utf8');
+      }
+    }
+  }
+
+  visit(rootDir);
+}
+
+module.exports = {
+  copyDirectoryRecursive,
+  ensureKeepFilesForEmptyDirs,
+  isDirectoryEmpty,
+  pathExists,
+  replacePlaceholdersInTextFiles,
+};

package/lib/scaffold.js

@@ -0,0 +1,69 @@
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const {
+  copyDirectoryRecursive,
+  ensureKeepFilesForEmptyDirs,
+  isDirectoryEmpty,
+  pathExists,
+  replacePlaceholdersInTextFiles,
+} = require('./fs-utils');
+
+function scaffoldProject(options) {
+  const {
+    projectName,
+    targetDir,
+    template,
+    dryRun,
+    noGit,
+    logger,
+  } = options;
+
+  const templateDir = path.resolve(__dirname, '..', 'templates', template);
+  if (!pathExists(templateDir)) {
+    throw new Error(`Unknown template: ${template}`);
+  }
+
+  if (pathExists(targetDir) && !isDirectoryEmpty(targetDir)) {
+    throw new Error(`Target directory already exists and is not empty: ${targetDir}`);
+  }
+
+  logger(`[info] template=${template}`);
+  logger(`[info] project=${projectName}`);
+  logger(`[info] target=${targetDir}`);
+
+  copyDirectoryRecursive(templateDir, targetDir, { dryRun, logger });
+
+  if (dryRun) {
+    logger('[dry-run] placeholder replacement skipped (no files written)');
+    logger('[dry-run] empty-dir .keep check skipped (no files written)');
+  } else {
+    replacePlaceholdersInTextFiles(
+      targetDir,
+      { '{{PROJECT_NAME}}': projectName },
+      { dryRun, logger }
+    );
+
+    ensureKeepFilesForEmptyDirs(targetDir, { dryRun, logger });
+  }
+
+  if (!noGit) {
+    if (dryRun) {
+      logger(`[git] would run: git init (${targetDir})`);
+    } else {
+      const result = spawnSync('git', ['init'], {
+        cwd: targetDir,
+        stdio: 'ignore',
+      });
+
+      if (result.status !== 0) {
+        logger('[warn] git init failed; continue manually if needed.');
+      } else {
+        logger('[git] initialized repository');
+      }
+    }
+  }
+}
+
+module.exports = {
+  scaffoldProject,
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "create-agentic-repo",
+  "version": "0.1.0",
+  "description": "Scaffold context-lean Agentic Repo Harness v2 workspaces.",
+  "license": "MIT",
+  "author": "",
+  "type": "commonjs",
+  "main": "lib/cli.js",
+  "bin": {
+    "create-agentic-repo": "bin/create-agentic-repo.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "smoke": "node scripts/smoke-test.js",
+    "test": "npm run smoke"
+  },
+  "keywords": [
+    "agentic",
+    "scaffold",
+    "cli",
+    "harness",
+    "spec-driven"
+  ]
+}

package/templates/minimal/00_inbox/README.md

@@ -0,0 +1,8 @@
+# 00_inbox
+
+Drop-only zone for raw context.
+
+Rules:
+- Put everything here first: notes, old docs, emails, links, dumps.
+- Do not clean, rewrite, or organize here.
+- Distill later into `02_context/`.

package/templates/minimal/01_harness/RULES.md

@@ -0,0 +1,33 @@
+# RULES
+
+These rules are always-on.
+
+## Truth and unknowns
+- Do not invent facts.
+- If information is missing, mark it as `Unknown`.
+- Ask focused questions only when needed to proceed.
+
+## Anti-bloat
+- Do not copy `00_inbox` into working files.
+- Keep `02_context` readable in 5 minutes.
+- Move heavy guidance into `shared/skills/`.
+
+## Spec discipline
+- Work from one active spec at a time in `03_specs/now/`.
+- Update acceptance criteria before shipping.
+- Keep backlog items in `03_specs/backlog.md` as one-line entries.
+
+## Output discipline
+- Final deliverables must go to `04_outputs/`.
+- Working debris goes to `05_scratch/`.
+- Use predictable names for deliverables: `YYYY-MM-DD_topic_v1.md`.
+
+## QA gate before close
+- Verify each acceptance criterion explicitly.
+- List unresolved `Unknown` items.
+- State risks and next step if not done.
+
+## Naming and format
+- Use clear file names and short headings.
+- Prefer concise bullets over long prose.
+- Keep docs actionable and skimmable.

package/templates/minimal/01_harness/SKILLS_INDEX.md

@@ -0,0 +1,7 @@
+# SKILLS_INDEX
+
+- `distill-context` (heavy/manual): distills raw inbox into compact context files.
+- `write-spec` (light): creates one SDD-light spec from distilled context.
+- `ship-output` (light): produces the final deliverable in `04_outputs/`.
+- `qa-review` (light): validates output against acceptance checklist.
+- `skill-creator` (strategic/heavy): creates and iterates skills with eval loop.

package/templates/minimal/01_harness/STACK.md

@@ -0,0 +1,8 @@
+# STACK
+
+Default: N/A (docs-first workspace).
+
+If code is introduced later, track here:
+- Runtime/framework:
+- Project layout conventions:
+- Build/test/dev commands:

package/templates/minimal/01_harness/TASKFLOW.md

@@ -0,0 +1,51 @@
+# TASKFLOW
+
+Use this loop every time:
+
+1. Seed
+2. Distill
+3. Spec
+4. Ship
+5. QA
+
+Only one active spec at a time.
+
+## Distill prompt (copy/paste)
+
+```text
+Read 00_inbox/ and distill only what is needed into:
+- 02_context/BRIEF.md
+- 02_context/FACTS.md
+- 02_context/CONSTRAINTS.md
+- 02_context/LINKS.md
+- 02_context/GLOSSARY.md (if needed)
+
+Rules:
+- keep total context readable in 5 minutes
+- separate facts from assumptions
+- mark unknowns explicitly
+- do not move raw dumps into 02_context
+```
+
+## Write spec prompt (copy/paste)
+
+```text
+Using 02_context, create one active spec in 03_specs/now/001_now.md with:
+- Outcome
+- Scope / No-scope
+- Inputs
+- Deliverable path and format
+- Acceptance criteria checklist
+- Risks / edge cases
+- Open questions (max 8)
+
+Keep it execution-ready and concise.
+```
+
+## QA gate checklist
+
+- [ ] Deliverable exists in `04_outputs/`
+- [ ] Acceptance criteria all checked
+- [ ] Unknowns listed
+- [ ] Risks noted with mitigation
+- [ ] Next action is clear

package/templates/minimal/02_context/BRIEF.md

@@ -0,0 +1,7 @@
+# BRIEF
+
+- What this project is:
+- Who it is for:
+- Measurable outcome:
+- Time horizon:
+- Success definition:

package/templates/minimal/02_context/CONSTRAINTS.md

@@ -0,0 +1,9 @@
+# CONSTRAINTS
+
+Track real constraints only.
+
+- Budget:
+- Time:
+- Tooling limits:
+- Non-negotiables:
+- Tone/brand constraints:

package/templates/minimal/02_context/FACTS.md

@@ -0,0 +1,10 @@
+# FACTS
+
+List only verifiable facts.
+
+Format:
+- Fact:
+  Source:
+  Confidence: high|medium|low
+
+If source is missing, mark `Unknown source`.

package/templates/minimal/02_context/GLOSSARY.md

@@ -0,0 +1,6 @@
+# GLOSSARY
+
+Only include terms needed to avoid ambiguity.
+
+- Term:
+  Definition:

package/templates/minimal/02_context/LINKS.md

@@ -0,0 +1,6 @@
+# LINKS
+
+Useful references with one-line relevance.
+
+- URL:
+  Why it matters:

package/templates/minimal/03_specs/backlog.md

@@ -0,0 +1,6 @@
+# BACKLOG
+
+One line per item.
+
+- [ ] Example: define ICP messaging draft
+- [ ] Example: draft outreach sequence

package/templates/minimal/03_specs/decisions.md

@@ -0,0 +1,5 @@
+# DECISIONS
+
+Short decision log.
+
+- 2026-03-01: Decision template initialized. Status: pending

package/templates/minimal/03_specs/now/001_now.md

@@ -0,0 +1,35 @@
+# 001_now
+
+## Outcome
+- What must exist at the end:
+
+## Scope
+- In scope:
+- Out of scope:
+
+## Inputs
+- Files:
+- Links:
+- Data:
+
+## Deliverable
+- Path: `04_outputs/YYYY-MM-DD_topic_v1.md`
+- Format:
+
+## Acceptance Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+- [ ] Criterion 4
+- [ ] Criterion 5
+- [ ] Criterion 6
+- [ ] Criterion 7
+- [ ] Criterion 8
+
+## Risks and Edge Cases
+- Risk:
+- Edge case:
+
+## Open Questions
+- Q1:
+- Q2:

package/templates/minimal/README.md

@@ -0,0 +1,10 @@
+# {{PROJECT_NAME}}
+
+Agentic Repo Harness v2 workspace.
+
+## Start Here
+
+1. Drop all raw material into `00_inbox/`.
+2. Use `01_harness/TASKFLOW.md` to run Seed -> Distill -> Spec -> Ship -> QA.
+3. Keep one active spec in `03_specs/now/`.
+4. Put deliverables in `04_outputs/`.

package/templates/minimal/runners/antigravity.md

@@ -0,0 +1,7 @@
+# Antigravity Runner
+
+1. Anchor workflow on `01_harness/` files.
+2. Delegate heavy tasks via relevant skill folders in `shared/skills/`.
+3. Keep context distilled in `02_context/` and work from one spec.
+4. Route deliverables to `04_outputs/`.
+5. Finish with QA gate verification.

package/templates/minimal/runners/claude.md

@@ -0,0 +1,7 @@
+# Claude Runner
+
+1. Read `01_harness/RULES.md` and `01_harness/TASKFLOW.md` first.
+2. Load only the needed skill from `shared/skills/`.
+3. Keep one active spec in `03_specs/now/`.
+4. Write final deliverables to `04_outputs/`.
+5. Run QA gate from `TASKFLOW.md` before closing.

package/templates/minimal/runners/codex.md

@@ -0,0 +1,7 @@
+# Codex Runner
+
+1. Start with `01_harness/RULES.md` and `TASKFLOW.md`.
+2. Use on-demand skills under `shared/skills/` for heavy workflows.
+3. Execute from one active spec only.
+4. Store final artifacts in `04_outputs/`.
+5. Complete QA checklist before marking done.