niuma-harness 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xudeyiyi
+
+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,105 @@
+# Niuma Harness
+
+Initialize an AI engineering harness for a project workspace.
+
+Niuma Harness creates a lightweight documentation scaffold that helps AI coding tools understand project context, rules, workflows, and task notes.
+
+## Quick start
+
+```bash
+npx niuma-harness init . --agent claude
+```
+
+Interactive mode is available when `--agent` is omitted in a TTY:
+
+```bash
+npx niuma-harness init
+```
+
+## CLI
+
+```bash
+niuma-harness init [target] [options]
+```
+
+### Options
+
+| Option | Description |
+|---|---|
+| `--agent <name>` | `claude`, `codex`, `opencode`, or `multi` |
+| `--harness-dir <name>` | Directory to create inside target, default: `harness` |
+| `--rules <mode>` | `copy` or `empty`, default: `copy` |
+| `--flat` | Write directly into target instead of `target/harness` |
+| `--force` | Overwrite existing scaffold files |
+| `--dry-run` | Print planned actions without writing files |
+| `-h`, `--help` | Show help |
+
+## Examples
+
+```bash
+npx niuma-harness init . --agent claude
+npx niuma-harness init ./workspace --agent codex --rules empty
+npx niuma-harness init ./workspace --agent opencode --dry-run
+npx niuma-harness init ./workspace --agent multi --harness-dir ai-harness
+npx niuma-harness init ./workspace --agent claude --flat
+```
+
+## Agent modes
+
+| Agent | Generated entry file |
+|---|---|
+| `claude` | `CLAUDE.md` |
+| `codex` | `AGENTS.md` |
+| `opencode` | `AGENTS.md` |
+| `multi` | `CLAUDE.md` and `AGENTS.md` |
+
+## Generated structure
+
+Default output:
+
+```text
+workspace/
+  harness/
+    CLAUDE.md or AGENTS.md
+    HARNESS_GUIDE.md
+    docs/
+      index.md
+      project-context.md
+      automation/
+        hooks.md
+      process/
+        task-triage.md
+        bugfix.md
+        feature-development.md
+      rules/
+        common/
+          coding-style.md
+          testing.md
+          security.md
+      tasks/
+        README.md
+```
+
+Use `--flat` to write the same scaffold directly into the target directory instead of creating `harness/`.
+
+## Rules mode
+
+`--rules copy` is the default and creates starter rule content.
+
+```bash
+npx niuma-harness init . --agent claude --rules copy
+```
+
+`--rules empty` creates the same rule files with empty content, useful when a team wants to fill its own rules from scratch.
+
+```bash
+npx niuma-harness init . --agent claude --rules empty
+```
+
+## Development
+
+```bash
+npm test
+npm run pack:dry
+node bin/niuma-harness.js init . --agent claude --dry-run
+```

package/bin/niuma-harness.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const { main } = require('../src/cli');
+
+main(process.argv.slice(2)).catch((error) => {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "niuma-harness",
+  "version": "0.0.1",
+  "description": "Initialize an AI engineering harness for a project workspace.",
+  "type": "commonjs",
+  "bin": {
+    "niuma-harness": "bin/niuma-harness.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node test/cli.test.js",
+    "check": "npm test",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "keywords": [
+    "ai",
+    "harness",
+    "claude-code",
+    "codex",
+    "openCode",
+    "agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/739188210/niuma-harness.git"
+  },
+  "bugs": {
+    "url": "https://github.com/739188210/niuma-harness/issues"
+  },
+  "homepage": "https://github.com/739188210/niuma-harness#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "author": "xudeyiyi"
+}

package/src/args.js

@@ -0,0 +1,176 @@
+const SUPPORTED_AGENTS = new Set(['claude', 'codex', 'opencode', 'multi']);
+const SUPPORTED_RULES = new Set(['copy', 'empty']);
+
+function parseArgs(argv) {
+  const options = {
+    command: null,
+    targetDir: null,
+    agent: null,
+    rules: 'copy',
+    harnessDir: 'harness',
+    flat: false,
+    force: false,
+    dryRun: false,
+    help: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+      continue;
+    }
+
+    if (arg === '--flat') {
+      options.flat = true;
+      continue;
+    }
+
+    if (arg === '--force') {
+      options.force = true;
+      continue;
+    }
+
+    if (arg === '--dry-run') {
+      options.dryRun = true;
+      continue;
+    }
+
+    if (arg === '--agent' || arg === '--rules' || arg === '--harness-dir') {
+      const value = argv[index + 1];
+      if (!value || value.startsWith('-')) {
+        throw new Error(`${arg} requires a value.`);
+      }
+      assignOption(options, arg.slice(2), value);
+      index += 1;
+      continue;
+    }
+
+    if (arg.startsWith('--agent=') || arg.startsWith('--rules=') || arg.startsWith('--harness-dir=')) {
+      const [name, value] = splitLongOption(arg);
+      assignOption(options, name, value);
+      continue;
+    }
+
+    if (arg.startsWith('-')) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+
+    if (!options.command) {
+      options.command = arg;
+      continue;
+    }
+
+    if (!options.targetDir) {
+      options.targetDir = arg;
+      continue;
+    }
+
+    throw new Error(`Unexpected argument: ${arg}`);
+  }
+
+  options.agent = normalizeAgent(options.agent);
+  options.rules = normalizeRules(options.rules);
+  options.harnessDir = normalizeHarnessDir(options.harnessDir);
+
+  return options;
+}
+
+function assignOption(options, name, value) {
+  if (name === 'agent') {
+    options.agent = value;
+    return;
+  }
+
+  if (name === 'rules') {
+    options.rules = value;
+    return;
+  }
+
+  if (name === 'harness-dir') {
+    options.harnessDir = value;
+    return;
+  }
+
+  throw new Error(`Unknown option: --${name}`);
+}
+
+function splitLongOption(arg) {
+  const equalsIndex = arg.indexOf('=');
+  const name = arg.slice(2, equalsIndex);
+  const value = arg.slice(equalsIndex + 1);
+
+  if (!value) {
+    throw new Error(`--${name} requires a value.`);
+  }
+
+  return [name, value];
+}
+
+function normalizeAgent(agent) {
+  if (!agent) {
+    return null;
+  }
+
+  const value = String(agent).trim().toLowerCase();
+  if (SUPPORTED_AGENTS.has(value)) {
+    return value;
+  }
+
+  throw new Error(`--agent must be one of: claude, codex, opencode, multi. Received: ${agent}`);
+}
+
+function normalizeRules(rules) {
+  const value = String(rules || 'copy').trim().toLowerCase();
+  if (SUPPORTED_RULES.has(value)) {
+    return value;
+  }
+
+  throw new Error(`--rules must be one of: copy, empty. Received: ${rules}`);
+}
+
+function normalizeHarnessDir(harnessDir) {
+  const value = String(harnessDir || 'harness').trim();
+  if (!value) {
+    throw new Error('--harness-dir cannot be empty.');
+  }
+
+  if (value === '.' || value.includes('..') || value.includes('/') || value.includes('\\')) {
+    throw new Error('--harness-dir must be a simple directory name.');
+  }
+
+  if (!/^[A-Za-z0-9._-]+$/.test(value)) {
+    throw new Error('--harness-dir may only contain letters, numbers, dots, underscores, and dashes.');
+  }
+
+  return value;
+}
+
+function getHelpText() {
+  return `Usage:
+  niuma-harness init [target] [options]
+
+Options:
+  --agent <name>         claude | codex | opencode | multi
+  --harness-dir <name>   Directory to create inside target, default: harness
+  --rules <mode>         copy | empty, default: copy
+  --flat                 Write directly into target instead of target/harness
+  --force                Overwrite existing scaffold files
+  --dry-run              Print planned actions without writing files
+  -h, --help             Show help
+
+Examples:
+  niuma-harness init . --agent claude
+  niuma-harness init D:\\work\\app --agent codex --rules empty
+  niuma-harness init . --agent multi --harness-dir ai-harness
+  niuma-harness init . --agent opencode --flat --dry-run`;
+}
+
+module.exports = {
+  parseArgs,
+  normalizeAgent,
+  normalizeRules,
+  normalizeHarnessDir,
+  getHelpText,
+};

package/src/cli.js

@@ -0,0 +1,23 @@
+const { parseArgs, getHelpText } = require('./args');
+const { chooseAgent } = require('./prompts');
+const { runInit } = require('./scaffold');
+
+async function main(argv) {
+  const options = parseArgs(argv);
+
+  if (options.help || !options.command) {
+    console.log(getHelpText());
+    return;
+  }
+
+  if (options.command !== 'init') {
+    throw new Error(`Unknown command: ${options.command}. Only "init" is supported.`);
+  }
+
+  options.agent = await chooseAgent(options.agent);
+  runInit(options);
+}
+
+module.exports = {
+  main,
+};

package/src/prompts.js

@@ -0,0 +1,61 @@
+const readline = require('readline');
+const { normalizeAgent } = require('./args');
+
+function ask(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+async function chooseAgent(agent) {
+  const normalized = normalizeAgent(agent);
+  if (normalized) {
+    return normalized;
+  }
+
+  if (!process.stdin.isTTY) {
+    throw new Error('Missing --agent. Use --agent claude, --agent codex, --agent opencode, or --agent multi.');
+  }
+
+  while (true) {
+    const answer = await ask([
+      'Choose AI coding agent:',
+      '  1. claude   -> generate CLAUDE.md',
+      '  2. codex    -> generate AGENTS.md',
+      '  3. opencode -> generate AGENTS.md',
+      '  4. multi    -> generate CLAUDE.md and AGENTS.md',
+      'Enter claude/codex/opencode/multi or 1/2/3/4: ',
+    ].join('\n'));
+
+    try {
+      return normalizeAgentAlias(answer);
+    } catch {
+      console.log('Please enter claude, codex, opencode, multi, 1, 2, 3, or 4.');
+    }
+  }
+}
+
+function normalizeAgentAlias(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  const aliases = {
+    1: 'claude',
+    2: 'codex',
+    3: 'opencode',
+    4: 'multi',
+  };
+
+  return normalizeAgent(aliases[normalized] || normalized);
+}
+
+module.exports = {
+  ask,
+  chooseAgent,
+};

package/src/scaffold.js

@@ -0,0 +1,207 @@
+const fs = require('fs');
+const path = require('path');
+
+const ROOT_DIR = path.resolve(__dirname, '..');
+const TEMPLATE_DIR = path.join(ROOT_DIR, 'templates');
+const MANIFEST_PATH = path.join(TEMPLATE_DIR, 'manifest.json');
+
+function runInit(options) {
+  const workspaceDir = path.resolve(options.targetDir || '.');
+  const targetDir = options.flat ? workspaceDir : path.join(workspaceDir, options.harnessDir);
+  const manifest = loadManifest();
+  validateManifest(manifest);
+
+  const variables = {
+    ENTRY_FILES: getEntryFilesForAgent(options.agent).join(', '),
+    HARNESS_DIR: options.flat ? '.' : options.harnessDir,
+  };
+
+  console.log(options.dryRun ? 'DRY RUN: preview scaffold changes' : 'Initializing niuma harness');
+  console.log(`Workspace: ${workspaceDir}`);
+  console.log(`Target: ${targetDir}`);
+  console.log(`Agent: ${options.agent}`);
+  console.log(`Rules: ${options.rules}`);
+
+  printAction(ensureDir(targetDir, options.dryRun), targetDir);
+
+  for (const directory of manifest.directories) {
+    const targetPath = safeResolveInside(targetDir, directory, 'directory target');
+    printAction(ensureDir(targetPath, options.dryRun), targetPath);
+  }
+
+  for (const entryFile of getEntryFilesForAgent(options.agent)) {
+    const templatePath = entryFile === 'CLAUDE.md' ? 'entry/CLAUDE.md' : 'entry/AGENTS.md';
+    const targetPath = safeResolveInside(targetDir, entryFile, 'entry target');
+    const content = renderTemplate(templatePath, { ...variables, ENTRY_FILE: entryFile });
+    printAction(writeFile(targetPath, content, options), targetPath);
+  }
+
+  for (const file of manifest.templateFiles) {
+    const targetPath = safeResolveInside(targetDir, file.target, 'template target');
+    const content = renderTemplate(file.template, variables);
+    printAction(writeFile(targetPath, content, options), targetPath);
+  }
+
+  for (const file of manifest.ruleFiles) {
+    const targetPath = safeResolveInside(targetDir, file.target, 'rule target');
+    const content = options.rules === 'copy' ? renderTemplate(file.template, variables) : '';
+    printAction(writeFile(targetPath, content, options), targetPath);
+  }
+
+  console.log('Done. Read HARNESS_GUIDE.md and fill docs/index.md for your project.');
+}
+
+function loadManifest() {
+  return JSON.parse(fs.readFileSync(MANIFEST_PATH, 'utf8'));
+}
+
+function validateManifest(manifest) {
+  for (const directory of manifest.directories || []) {
+    validateRelativePath(directory, 'manifest directory');
+  }
+
+  for (const file of [...(manifest.templateFiles || []), ...(manifest.ruleFiles || [])]) {
+    validateRelativePath(file.target, 'manifest target');
+    validateRelativePath(file.template, 'manifest template');
+    safeResolveInside(TEMPLATE_DIR, file.template, 'manifest template');
+  }
+}
+
+function getEntryFilesForAgent(agent) {
+  if (agent === 'claude') {
+    return ['CLAUDE.md'];
+  }
+
+  if (agent === 'codex' || agent === 'opencode') {
+    return ['AGENTS.md'];
+  }
+
+  if (agent === 'multi') {
+    return ['CLAUDE.md', 'AGENTS.md'];
+  }
+
+  throw new Error(`Unsupported agent: ${agent}`);
+}
+
+function readTemplate(relativePath) {
+  const templatePath = safeResolveInside(TEMPLATE_DIR, relativePath, 'template path');
+  return fs.readFileSync(templatePath, 'utf8');
+}
+
+function renderTemplate(relativePath, variables) {
+  let content = readTemplate(relativePath);
+  for (const [key, value] of Object.entries(variables)) {
+    content = content.split(`{{${key}}}`).join(value);
+  }
+  return content;
+}
+
+function ensureDir(dirPath, dryRun) {
+  assertNoSymlinkInPath(dirPath);
+
+  if (fs.existsSync(dirPath)) {
+    const stat = fs.lstatSync(dirPath);
+    if (!stat.isDirectory()) {
+      throw new Error(`Path exists but is not a directory: ${dirPath}`);
+    }
+    return 'skip';
+  }
+
+  if (!dryRun) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+  return 'create';
+}
+
+function writeFile(filePath, content, options) {
+  assertNoSymlinkInPath(filePath);
+
+  const exists = fs.existsSync(filePath);
+  if (exists && !options.force) {
+    return 'skip';
+  }
+
+  if (exists) {
+    const stat = fs.lstatSync(filePath);
+    if (!stat.isFile()) {
+      throw new Error(`Path exists but is not a regular file: ${filePath}`);
+    }
+  }
+
+  if (!options.dryRun) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content, 'utf8');
+  }
+
+  if (exists && options.force) {
+    return 'overwrite';
+  }
+  return 'create';
+}
+
+function validateRelativePath(relativePath, label) {
+  if (!relativePath || typeof relativePath !== 'string') {
+    throw new Error(`Invalid ${label}: path must be a non-empty string.`);
+  }
+
+  if (path.isAbsolute(relativePath)) {
+    throw new Error(`Invalid ${label}: absolute paths are not allowed: ${relativePath}`);
+  }
+
+  const segments = relativePath.split(/[\\/]+/);
+  if (segments.includes('..') || segments.includes('')) {
+    throw new Error(`Invalid ${label}: path must stay inside the scaffold: ${relativePath}`);
+  }
+}
+
+function safeResolveInside(baseDir, relativePath, label) {
+  validateRelativePath(relativePath, label);
+  const base = path.resolve(baseDir);
+  const resolved = path.resolve(base, relativePath);
+  if (resolved !== base && !resolved.startsWith(`${base}${path.sep}`)) {
+    throw new Error(`Invalid ${label}: path escapes base directory: ${relativePath}`);
+  }
+  return resolved;
+}
+
+function assertNoSymlinkInPath(targetPath) {
+  const resolved = path.resolve(targetPath);
+  const root = path.parse(resolved).root;
+  const relative = path.relative(root, resolved);
+  const parts = relative ? relative.split(path.sep) : [];
+  let current = root;
+
+  for (const part of parts) {
+    current = path.join(current, part);
+    if (!fs.existsSync(current)) {
+      continue;
+    }
+
+    const stat = fs.lstatSync(current);
+    if (stat.isSymbolicLink()) {
+      throw new Error(`Refusing to write through symlink: ${current}`);
+    }
+  }
+}
+
+function printAction(action, targetPath) {
+  const label = {
+    create: 'CREATE',
+    overwrite: 'OVERWRITE',
+    skip: 'SKIP',
+  }[action] || action.toUpperCase();
+
+  console.log(`${label.padEnd(9)} ${targetPath}`);
+}
+
+module.exports = {
+  runInit,
+  loadManifest,
+  validateManifest,
+  getEntryFilesForAgent,
+  renderTemplate,
+  ensureDir,
+  writeFile,
+  safeResolveInside,
+  assertNoSymlinkInPath,
+};

package/templates/core/HARNESS_GUIDE.md

@@ -0,0 +1,35 @@
+# Niuma Harness Guide
+
+This directory contains the AI engineering harness for the workspace.
+
+Generated entry file(s): `{{ENTRY_FILES}}`
+
+## Purpose
+
+The harness gives AI coding tools a stable operating context:
+
+- where project code and docs live
+- which rules to follow
+- which process to use for common task types
+- where to record task state and verification evidence
+
+## First steps
+
+1. Fill `docs/index.md` with the real project paths and important docs.
+2. Fill `docs/project-context.md` with stable project facts.
+3. Adjust `docs/rules/` to match your team conventions.
+4. Use `docs/process/` as the default workflow reference.
+5. Store multi-step task notes in `docs/tasks/`.
+
+## Directory map
+
+- `docs/index.md`: project map and reading order.
+- `docs/project-context.md`: stable project context.
+- `docs/rules/`: coding, testing, and security rules.
+- `docs/process/`: reusable task workflows.
+- `docs/automation/`: automation and hook intent notes.
+- `docs/tasks/`: task records and handoff notes.
+
+## Maintenance rule
+
+Keep long-lived facts in `docs/project-context.md`. Keep temporary investigation notes in `docs/tasks/` or another task-local location.

package/templates/core/docs/automation/hooks.md

@@ -0,0 +1,16 @@
+# Automation and Hook Intent
+
+This MVP does not install tool-specific hooks automatically.
+
+Use this document to describe automation you may want to map to Claude Code hooks, Codex hooks, opencode plugins, Git hooks, or CI jobs.
+
+| Intent | Trigger | Suggested command | Status |
+|---|---|---|---|
+| Format changed files | after file edit | `<fill command>` | planned |
+| Run focused tests | before completion | `<fill command>` | planned |
+| Check secrets | before commit or release | `<fill command>` | planned |
+| Verify build | before release | `<fill command>` | planned |
+
+## Maintenance
+
+Keep actual hook configuration in the relevant tool-specific location. Keep this file as the shared source for automation intent.

package/templates/core/docs/index.md

@@ -0,0 +1,38 @@
+# Harness Index
+
+Use this file as the map for AI tools working in this workspace.
+
+## Code locations
+
+- Backend: `<fill path, e.g. ../backend>`
+- Frontend: `<fill path, e.g. ../frontend>`
+- Shared packages: `<fill path or N/A>`
+
+## Required reading
+
+- Project context: `docs/project-context.md`
+- Task workflows: `docs/process/`
+- Rules: `docs/rules/`
+- Automation notes: `docs/automation/hooks.md`
+
+## Task workflows
+
+- Task triage: `docs/process/task-triage.md`
+- Bug fixes: `docs/process/bugfix.md`
+- Feature development: `docs/process/feature-development.md`
+
+## Verification commands
+
+Document project-specific commands here:
+
+```bash
+# tests
+<fill command>
+
+# lint/typecheck/build
+<fill command>
+```
+
+## Maintenance
+
+Update this index when project paths, important docs, or standard workflows change.

package/templates/core/docs/process/bugfix.md

@@ -0,0 +1,19 @@
+# Bugfix Process
+
+## Goal
+
+Fix a defect with evidence that the behavior is corrected and existing behavior is not unexpectedly broken.
+
+## Steps
+
+1. Understand the symptom and expected behavior.
+2. Locate the relevant code path.
+3. Reproduce the issue with a test, command, or manual steps when practical.
+4. Implement the smallest safe fix.
+5. Run focused verification.
+6. Run broader regression checks when the touched area is shared.
+7. Report root cause, changed files, verification result, and residual risk.
+
+## Notes
+
+If reproduction is not possible in the current environment, document the missing condition and the exact verification steps to run later.

package/templates/core/docs/process/feature-development.md

@@ -0,0 +1,29 @@
+# Feature Development Process
+
+## Goal
+
+Deliver a feature through clear requirements, implementation notes, and verification evidence.
+
+## Lightweight flow
+
+1. Clarify the goal and acceptance criteria.
+2. Read project context and relevant existing implementation patterns.
+3. Plan the smallest safe implementation path.
+4. Add or update tests for behavior when practical.
+5. Implement the feature.
+6. Run relevant verification commands.
+7. Record what changed, what passed, what failed, and what remains.
+
+## When to pause
+
+Pause and ask before:
+
+- changing public APIs or data contracts
+- adding dependencies
+- changing authentication, authorization, or security-sensitive behavior
+- making irreversible data changes
+- proceeding when acceptance criteria are unclear
+
+## Task notes
+
+For multi-step features, create a task folder under `docs/tasks/<task-name>/` and keep context, plan, and verification notes there.

package/templates/core/docs/process/task-triage.md

@@ -0,0 +1,29 @@
+# Task Triage Process
+
+Use this process before choosing a more specific workflow.
+
+## 1. Classify the task
+
+- Question or explanation only
+- Small edit
+- Bug fix
+- Feature development
+- Refactor
+- Security-sensitive change
+- Documentation update
+
+## 2. Identify required context
+
+- Read `docs/index.md`.
+- Read `docs/project-context.md` when design or code changes are involved.
+- Read relevant rules under `docs/rules/`.
+
+## 3. Choose workflow
+
+- Bug fix: `docs/process/bugfix.md`
+- Feature development: `docs/process/feature-development.md`
+- Other tasks: use the closest workflow and keep notes in `docs/tasks/` when needed.
+
+## 4. Confirm blockers
+
+Ask for clarification when the task changes public contracts, adds dependencies, touches security-sensitive behavior, or lacks enough acceptance criteria.

package/templates/core/docs/project-context.md

@@ -0,0 +1,52 @@
+# Project Context
+
+This file stores stable facts about the project. Do not use it for temporary investigation notes.
+
+## Metadata
+
+- Created:
+- Last updated:
+- Scan scope:
+- Known gaps:
+
+## Project summary
+
+Describe the product, main users, and primary business/domain goals.
+
+## Technology stack
+
+- Runtime/language:
+- Frameworks:
+- Package manager:
+- Database/storage:
+- Test framework:
+
+## Module structure
+
+Document stable module boundaries and important paths.
+
+## Engineering conventions
+
+- API response format:
+- Error handling:
+- Auth/security:
+- Logging:
+- Configuration:
+
+## Build and verification commands
+
+```bash
+# install
+
+# test
+
+# lint/typecheck/build
+```
+
+## Reference implementations
+
+List stable reference modules or features that agents should reuse as patterns.
+
+## Open questions
+
+Track project-level questions that cannot be answered from current files.

package/templates/core/docs/rules/common/coding-style.md

@@ -0,0 +1,20 @@
+# Coding Style Rules
+
+## Principles
+
+- Prefer simple, readable code over clever abstractions.
+- Match the surrounding project style.
+- Make focused changes; do not refactor unrelated code.
+- Reuse existing utilities and patterns before adding new ones.
+
+## Naming
+
+- Use descriptive names.
+- Keep files and modules cohesive.
+- Avoid ambiguous abbreviations unless already common in the project.
+
+## Change discipline
+
+- Do not introduce new dependencies without explicit approval.
+- Do not change public contracts unless the task requires it and the risk is called out.
+- Remove only dead code introduced by the current change unless asked otherwise.

package/templates/core/docs/rules/common/security.md

@@ -0,0 +1,17 @@
+# Security Rules
+
+## Secrets
+
+- Never hardcode credentials, tokens, API keys, or private endpoints.
+- Use environment variables or the project's existing secret management pattern.
+
+## Inputs and outputs
+
+- Validate input at system boundaries.
+- Avoid unsafe shell execution and path handling.
+- Avoid rendering or logging sensitive data.
+
+## Risk handling
+
+Stop and ask before making security-sensitive changes when requirements are unclear.
+Document residual security risk in task notes or verification output.

package/templates/core/docs/rules/common/testing.md

@@ -0,0 +1,24 @@
+# Testing Rules
+
+## Default expectation
+
+Changes should be verified before being called complete.
+
+## Test-first preference
+
+For behavior changes:
+
+1. Reproduce the current behavior or failure.
+2. Add or update a focused test when practical.
+3. Implement the smallest fix.
+4. Run the relevant verification commands.
+
+## Reporting
+
+Always report:
+
+- commands run
+- whether they passed or failed
+- important skipped checks and why
+
+Do not claim completion when relevant tests fail unless the user explicitly accepts the remaining risk.

package/templates/core/docs/tasks/README.md

@@ -0,0 +1,15 @@
+# Task Notes
+
+Use this directory for multi-step task records, handoffs, and verification notes.
+
+Suggested structure:
+
+```text
+docs/tasks/<task-name>/
+  context.md
+  plan.md
+  verification.md
+  notes.md
+```
+
+Keep long-lived project facts in `docs/project-context.md`, not here.

package/templates/entry/AGENTS.md

@@ -0,0 +1,13 @@
+# Agent Entry
+
+This workspace uses a Niuma Harness documentation scaffold.
+
+Before starting work:
+
+1. Read `docs/index.md` to understand the project map.
+2. Read `docs/project-context.md` before design or code changes.
+3. Follow the relevant process under `docs/process/`.
+4. Follow shared rules under `docs/rules/`.
+5. Record task notes under `docs/tasks/` when work spans multiple steps.
+
+This file is the generic agent entry point for Codex, opencode, and compatible tools. Treat `docs/` as the source of truth for project context, process, and rules.

package/templates/entry/CLAUDE.md

@@ -0,0 +1,13 @@
+# Claude Code Entry
+
+This workspace uses a Niuma Harness documentation scaffold.
+
+Before starting work:
+
+1. Read `docs/index.md` to understand the project map.
+2. Read `docs/project-context.md` before design or code changes.
+3. Follow the relevant process under `docs/process/`.
+4. Follow shared rules under `docs/rules/`.
+5. Record task notes under `docs/tasks/` when work spans multiple steps.
+
+This file is only the Claude Code entry point. Treat `docs/` as the source of truth for project context, process, and rules.

package/templates/manifest.json

@@ -0,0 +1,58 @@
+{
+  "directories": [
+    "docs",
+    "docs/automation",
+    "docs/process",
+    "docs/rules",
+    "docs/rules/common",
+    "docs/tasks"
+  ],
+  "templateFiles": [
+    {
+      "target": "HARNESS_GUIDE.md",
+      "template": "core/HARNESS_GUIDE.md"
+    },
+    {
+      "target": "docs/index.md",
+      "template": "core/docs/index.md"
+    },
+    {
+      "target": "docs/project-context.md",
+      "template": "core/docs/project-context.md"
+    },
+    {
+      "target": "docs/process/task-triage.md",
+      "template": "core/docs/process/task-triage.md"
+    },
+    {
+      "target": "docs/process/bugfix.md",
+      "template": "core/docs/process/bugfix.md"
+    },
+    {
+      "target": "docs/process/feature-development.md",
+      "template": "core/docs/process/feature-development.md"
+    },
+    {
+      "target": "docs/automation/hooks.md",
+      "template": "core/docs/automation/hooks.md"
+    },
+    {
+      "target": "docs/tasks/README.md",
+      "template": "core/docs/tasks/README.md"
+    }
+  ],
+  "ruleFiles": [
+    {
+      "target": "docs/rules/common/coding-style.md",
+      "template": "core/docs/rules/common/coding-style.md"
+    },
+    {
+      "target": "docs/rules/common/testing.md",
+      "template": "core/docs/rules/common/testing.md"
+    },
+    {
+      "target": "docs/rules/common/security.md",
+      "template": "core/docs/rules/common/security.md"
+    }
+  ]
+}