mikoshi-construct 0.1.0

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "mikoshi-construct",
+  "type": "module",
+  "version": "0.1.0",
+  "packageManager": "pnpm@12.4.2",
+  "description": "Bootstrap for AI-native software projects. Start with a proven engineering workflow instead of an empty repository.",
+  "author": "Eli Tabrisov",
+  "license": "MIT",
+  "homepage": "https://github.com/e1i/mikoshi-construct#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/e1i/mikoshi-construct.git"
+  },
+  "bugs": "https://github.com/e1i/mikoshi-construct/issues",
+  "keywords": [
+    "claude-code",
+    "cursor",
+    "ai-agents",
+    "scaffold",
+    "bootstrap",
+    "openapi",
+    "harness",
+    "architecture",
+    "cli",
+    "ai-dlc"
+  ],
+  "bin": {
+    "construct": "dist/cli.js",
+    "miko": "dist/cli.js",
+    "mikoshi-construct": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli.ts",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "quality": "pnpm composition:check && pnpm lint && pnpm typecheck && pnpm test",
+    "prepublishOnly": "pnpm build",
+    "composition:render": "tsx scripts/composition/sync-docs.ts",
+    "composition:check": "tsx scripts/composition/check.ts",
+    "ci": "pnpm run quality",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "pnpm build && npm publish --provenance --access public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.0",
+    "citty": "^0.2.2",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^9.5.1",
+    "@changesets/changelog-github": "^1.0.0",
+    "@changesets/cli": "^3.0.0",
+    "@types/node": "^22.18.0",
+    "eslint": "^10.10.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.13",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.0",
+    "yaml": "^2.9.1"
+  }
+}

package/templates/ai/claude/CLAUDE.md.eta

@@ -0,0 +1,18 @@
+# {{projectName}}
+
+@AGENTS.md
+
+Everything an agent needs to know about this repository — product, module map, commands, harness,
+composition roots, dependency policy, high-effort areas, defects vs accepted variance — lives in
+[AGENTS.md](AGENTS.md), imported above. Repository-wide code rules are in `.claude/rules/`; the
+architecture, security and reasoning-budget rules in
+[architecture/principles.md](architecture/principles.md).
+
+## Working here with Claude Code
+
+- `/construct-discover` — fill or refresh the discovery blocks in AGENTS.md and `architecture/`.
+- `/plan <feature>` — decompose a feature into tasks with acceptance criteria and an effort class.
+- `/implement <task>` — run the reasoning-budget ladder: classify, implement at the lowest rung,
+  verify with `{{harnessCommand}}`, escalate only when verification proves it was not enough.
+- `construct doctor` (or `npx mikoshi-construct doctor`) — check that the baseline and discovery are
+  intact.

package/templates/ai/claude/CLAUDE.md.existing.eta

@@ -0,0 +1,15 @@
+## Construct
+
+This repository runs on a construct materialized by `mikoshi-construct` v{{constructVersion}}. The
+discovery blocks — product, module map, commands, composition roots, dependency policy, high-effort
+areas, defects vs accepted variance, open questions — live in [AGENTS.md](AGENTS.md); the
+architecture, security and reasoning-budget rules in
+[architecture/principles.md](architecture/principles.md); repository-wide code rules in
+`.claude/rules/`.
+
+- `/construct-discover` — fill or refresh the discovery blocks.
+- `/plan <feature>` — decompose a feature into tasks with acceptance criteria and an effort class.
+- `/implement <task>` — the reasoning-budget ladder: classify, implement at the lowest rung, verify
+  with `{{harnessCommand}}`, escalate only when verification proves it was not enough.
+- `construct doctor` (or `npx mikoshi-construct doctor`) — check that the baseline and discovery are
+  intact.

package/templates/ai/claude/_claude/agents/architect.md

@@ -0,0 +1,38 @@
+---
+name: architect
+description: High-effort design for an architecture, contract, composition or security change, or for a task an implementer reported as blocked or repeatedly failed. Reads and reasons; does not edit.
+model: inherit
+effort: xhigh
+tools: Read, Grep, Glob, Bash
+---
+
+You design; you do not implement. You may read anything and run read-only commands (`git log`,
+`git diff`, tests), but you never write files. Run `git` only when `git rev-parse --show-toplevel`
+is the directory that holds `construct.json`; a parent directory's repository tells you nothing about
+this one.
+
+Input you receive: the task, and on escalation either the implementer's question or the failure
+excerpts of the attempts so far.
+
+Work through, in this order, and write nothing down until you have:
+
+1. Which contract(s), domain boundaries, dependencies and composition the change touches.
+2. Whether an existing artifact already describes the area (API contract, composition model,
+   invariants table) and what in it must change first.
+3. The alternatives you considered and why the chosen one keeps the change local.
+4. Whether the API contract or a composition model must change; if so, that is part of the spec.
+5. The explicit constraints the implementer must respect, and the acceptance criteria that make
+   the task statable.
+
+Your final message is data, not prose. Return exactly one JSON object:
+
+```json
+{
+  "decision": "the design in a few sentences, including what stays unchanged and why",
+  "contractChanges": "operations or schemas to add or change in the API contract, or empty",
+  "compositionChanges": "composition model nodes or edges to change, or empty",
+  "constraints": ["one constraint per entry"],
+  "acceptance": ["one verifiable criterion per entry"],
+  "files": ["files to create or change"]
+}
+```

package/templates/ai/claude/_claude/agents/harness.md

@@ -0,0 +1,40 @@
+---
+name: harness
+description: Runs the repository's quality gate against the working tree and reports a structured verdict. Never edits. Use after an implementer so a pass is never self-reported.
+model: inherit
+effort: low
+tools: Bash, Read, Grep, Glob
+---
+
+You verify; you do not fix. Run the harness command(s) you are given against the current working
+tree and report what happened. If no command is given, run the harness command named in
+`construct.json` (`harness.command`), and fall back to `pnpm run quality`. If the repository's CLAUDE.md
+names extra commands for the area the diff touches, run those too.
+
+Git is usable only when `git rev-parse --show-toplevel` is the directory that holds `construct.json`.
+When it is not — the repository has no `.git`, or a parent directory's repository would answer — set
+`diffStat` to `not a git repository at <dir>`, and decide `contractChanged` and `testsWeakened` by
+reading the files the implementer's report names, never by a `git diff` that sees a different tree.
+
+When git is usable, also inspect `git diff` (staged and unstaged) for:
+
+- a deleted or renamed file under any `tests/` directory;
+- `.skip(` or `.only(` added to a test;
+- a change to an API contract file under `contracts/` (report it; the caller decides whether it was
+  expected).
+
+Report the security leg separately from the rest when a failure comes from a security lint rule,
+a contract security test or the secret scan, so the reader sees the invariant, not just the tool.
+
+Your final message is data, not prose. Return exactly one JSON object:
+
+```json
+{
+  "passed": true,
+  "failureExcerpt": "the failing command and its last relevant lines, empty when passed",
+  "securityFinding": "the invariant that failed, empty when none",
+  "diffStat": "output of git diff --stat",
+  "testsWeakened": false,
+  "contractChanged": false
+}
+```

package/templates/ai/claude/_claude/agents/implementer.md

@@ -0,0 +1,40 @@
+---
+name: implementer
+description: Low-effort implementer for a task with a statable acceptance criterion. Follows the neighbouring pattern under strict constraints, runs the harness, and returns a structured report instead of a guess.
+model: inherit
+effort: low
+tools: Read, Edit, Write, Grep, Glob, Bash
+---
+
+You implement exactly the task you are given, nothing more. The repository's CLAUDE.md files are
+already in your context; follow them.
+
+Input you receive: the task, the acceptance criteria, the harness command(s), optionally a design
+spec from the architect, and optionally the failure excerpt from the previous attempt.
+
+Constraints at this effort level:
+
+- Implement only the requested change. Follow the pattern of the neighbouring code.
+- Add no abstraction, no dependency, no layer. Touch no unrelated module.
+- When the task touches an HTTP route, change the API contract first, regenerate the shared
+  types, then implement.
+- Never delete, skip or weaken a test. A changed logic module ships its test in the same change.
+- Read the previous failure excerpt, if any, before touching code; fix the cause, not the symptom.
+- Run the harness before reporting. If it fails and you cannot see why within two attempts, report
+  `failed` with the excerpt rather than looping.
+- Do not commit.
+
+If the task is ambiguous about a contract, a boundary or which of two designs is meant, stop and
+report `blocked` with one precise question. Do not pick one.
+
+Your final message is data, not prose. Return exactly one JSON object:
+
+```json
+{
+  "status": "done | failed | blocked",
+  "summary": "one or two sentences on what changed",
+  "files": ["paths you changed"],
+  "harnessTail": "last lines of the harness output, empty when blocked",
+  "question": "the single question when blocked, otherwise empty"
+}
+```

package/templates/ai/claude/_claude/commands/plan.md

@@ -0,0 +1,24 @@
+---
+description: Turn a feature or issue into tasks that /implement can run — each with a statable acceptance criterion and an effort class.
+argument-hint: <feature, issue text or link>
+---
+
+Decompose `$ARGUMENTS` into tasks for the reasoning-budget ladder. Use the `architect` agent for the
+decomposition when the feature touches a contract, a composition model, a high-effort area from
+CLAUDE.md or a security invariant; otherwise reason it out directly.
+
+Rules:
+
+- Two to six tasks. Each task is independently verifiable by the harness and leaves the tree green.
+- Each task has two to four acceptance criteria that a harness run or a test can confirm. "Works" is
+  not a criterion; "GET /v1/things returns 200 with the `Thing` schema and the contract test passes" is.
+- Order tasks so the contract and composition changes come first, then implementation, then anything
+  that consumes the new behaviour.
+- Classify each task `low`, `medium` or `high` with the rules in `architecture/principles.md`
+  (Reasoning budget); a task touching a high-effort area, the contract, a composition model, the
+  dependency policy or a security invariant is `high`.
+- If the feature is ambiguous about a contract or a boundary, put one precise question first and stop
+  after it; do not plan on a guess.
+
+Output the tasks as a numbered list; for each, one line `/implement <task> — acceptance: …; effort:
+<class>` that can be pasted as-is. Do not implement anything.

package/templates/ai/claude/_claude/skills/implement/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: implement
+description: Implement a task through the reasoning-budget ladder — classify effort, run a low-effort implementer under constraints, verify with the harness, escalate only on repeated failure or ambiguity.
+user-invocable: true
+disable-model-invocation: true
+argument-hint: <task with an acceptance criterion>
+---
+
+Run the reasoning-budget ladder for the task in `$ARGUMENTS`. The rules are in the Reasoning budget
+section of `architecture/principles.md`; repo specifics (harness command, high-effort areas) are in the
+repository's CLAUDE.md and `construct.json`.
+
+1. Classify the effort class and tell the user the class and the one-line reason before anything
+   else. Read the repository's CLAUDE.md for its harness command and its high-effort areas. A task
+   that names or must touch a high-effort area, the API contract, a composition model, the
+   dependency policy or the security invariants is `high`. A new endpoint, a new integration or a
+   change across several modules is `medium`. Everything with an existing pattern to copy and a
+   contract already defined is `low`.
+2. Write the acceptance criteria in two to four verifiable lines. If the task has no statable
+   criterion, say so and stop; the ladder is not for one-line edits or open-ended exploration.
+3. Call the Workflow tool with `scriptPath` set to `scripts/construct/implement.workflow.mjs` (the ladder
+   script lives with the project's scripts, not under `.claude/`) and `args` as
+   a JSON object:
+   `{ "task": ..., "acceptance": [...], "effort": "low|medium|high", "harness": { "command": ..., "extra": [...] } }`
+   where `harness.command` comes from `construct.json` and `harness.extra` lists any area-specific
+   commands CLAUDE.md names for the files the task touches (usually empty).
+   The user's `/implement` invocation is the opt-in the tool requires.
+4. Record the run: append one JSON line to `.construct/runs.jsonl` (create the directory if needed)
+   with `at` (ISO time), `task` (first 120 characters), `effort` (the class you chose), `status`,
+   the rung that finished (`effort` from the result), `attempts` from the result, and the Workflow
+   tool's own accounting for the run — `agents`, `tokens`, `toolUses`, `seconds` — exactly as it
+   reported them. This log is what tunes the ladder later; workflow scripts have no filesystem
+   access, so it is written here, not by the script. `.construct/` is gitignored.
+5. Relay the result: status, the effort rung that succeeded and how many attempts it took, the
+   files changed, and the harness tail. When the status is `blocked`, put the architect's or
+   implementer's question to the user verbatim. When `failed`, give the last failure excerpt.
+   Unless `construct.json` sets `report.usage` to `false`, end with one usage line for this run,
+   from the Workflow tool's own accounting: agents, subagent tokens, tool uses, wall time — so the
+   cost of the rung that succeeded is on record next to the result. When `construct` is on the PATH,
+   add the per-agent split from `construct cost --last --json` (implementer, harness, architect);
+   when it is not, the Workflow accounting alone is the line — never guess numbers.
+6. Never commit. The user reviews the working tree first.

package/templates/ai/claude/scripts/construct/implement.workflow.mjs

@@ -0,0 +1,185 @@
+export const meta = {
+  name: 'implement',
+  description: 'Implement a task at low effort, verify with the harness, escalate on repeated failure or ambiguity',
+  phases: [
+    { title: 'Design', detail: 'architect, only for high effort or after a blocked or failed attempt' },
+    { title: 'Implement', detail: 'implementer at the current rung' },
+    { title: 'Verify', detail: 'harness against the working tree' },
+  ],
+}
+
+const LADDERS = {
+  low: ['low', 'low', 'medium', 'high'],
+  medium: ['medium', 'medium', 'high'],
+  high: ['high', 'high', 'xhigh'],
+}
+
+const REPORT = {
+  type: 'object',
+  required: ['status', 'summary', 'files', 'harnessTail', 'question'],
+  properties: {
+    status: { type: 'string', enum: ['done', 'failed', 'blocked'] },
+    summary: { type: 'string' },
+    files: { type: 'array', items: { type: 'string' } },
+    harnessTail: { type: 'string' },
+    question: { type: 'string' },
+  },
+}
+
+const VERDICT = {
+  type: 'object',
+  required: ['passed', 'failureExcerpt', 'securityFinding', 'diffStat', 'testsWeakened', 'contractChanged'],
+  properties: {
+    passed: { type: 'boolean' },
+    failureExcerpt: { type: 'string' },
+    securityFinding: { type: 'string' },
+    diffStat: { type: 'string' },
+    testsWeakened: { type: 'boolean' },
+    contractChanged: { type: 'boolean' },
+  },
+}
+
+const SPEC = {
+  type: 'object',
+  required: ['decision', 'contractChanges', 'compositionChanges', 'constraints', 'acceptance', 'files'],
+  properties: {
+    decision: { type: 'string' },
+    contractChanges: { type: 'string' },
+    compositionChanges: { type: 'string' },
+    constraints: { type: 'array', items: { type: 'string' } },
+    acceptance: { type: 'array', items: { type: 'string' } },
+    files: { type: 'array', items: { type: 'string' } },
+  },
+}
+
+const task = args.task
+const acceptance = args.acceptance ?? []
+const harness = { command: 'pnpm run quality', extra: [], ...(args.harness ?? {}) }
+const rungs = LADDERS[args.effort] ?? LADDERS.low
+
+function harnessPrompt() {
+  return [
+    `Harness command: ${harness.command}`,
+    harness.extra.length > 0 ? `Extra commands for the area this task touches: ${harness.extra.join(' && ')}` : '',
+    'Verify the current working tree and return the verdict object.',
+  ].filter(Boolean).join('\n')
+}
+
+function architectPrompt(reason) {
+  return [
+    `Task: ${task}`,
+    acceptance.length > 0 ? `Acceptance criteria so far:\n- ${acceptance.join('\n- ')}` : '',
+    reason,
+    'Return the design spec object.',
+  ].filter(Boolean).join('\n\n')
+}
+
+function implementerPrompt(spec, feedback) {
+  return [
+    `Task: ${task}`,
+    `Acceptance criteria:\n- ${(spec?.acceptance?.length ? spec.acceptance : acceptance).join('\n- ')}`,
+    `Harness: ${harness.command}${harness.extra.length > 0 ? ` (plus ${harness.extra.join(' && ')})` : ''}`,
+    spec == null
+      ? ''
+      : `Design spec from the architect:\n${spec.decision}\n\nContract changes: ${spec.contractChanges || 'none'}\nComposition changes: ${spec.compositionChanges || 'none'}\nConstraints:\n- ${spec.constraints.join('\n- ')}\nFiles: ${spec.files.join(', ')}`,
+    feedback == null ? '' : `The previous attempt failed the harness. Fix the cause of this before anything else:\n${feedback}`,
+    'Return the report object.',
+  ].filter(Boolean).join('\n\n')
+}
+
+let spec = null
+let feedback = null
+const attempts = []
+
+
+if (args.effort === 'high') {
+  phase('Design')
+  spec = await agent(architectPrompt('The task is classified as high effort; design it before any implementation.'), {
+    agentType: 'architect',
+    effort: 'xhigh',
+    phase: 'Design',
+    label: 'design',
+    schema: SPEC,
+  })
+}
+
+for (const [index, effort] of rungs.entries()) {
+  const rung = index + 1
+  phase('Implement')
+  log(`rung ${rung}/${rungs.length} @ ${effort}: implementing`)
+  const report = await agent(implementerPrompt(spec, feedback), {
+    agentType: 'implementer',
+    effort,
+    phase: 'Implement',
+    label: `implement ${rung}/${rungs.length} @ ${effort}`,
+    schema: REPORT,
+  })
+  if (report == null) {
+    attempts.push({ rung, effort, outcome: 'no report' })
+    continue
+  }
+
+  if (report.status === 'blocked') {
+    attempts.push({ rung, effort, outcome: 'blocked', question: report.question })
+    if (rung === rungs.length)
+      return { status: 'blocked', question: report.question, attempts }
+    spec = await agent(architectPrompt(`The implementer stopped on this question:\n${report.question}`), {
+      agentType: 'architect',
+      effort: 'xhigh',
+      phase: 'Design',
+      label: `design after blocked ${rung}`,
+      schema: SPEC,
+    })
+    feedback = null
+    log(`rung ${rung}/${rungs.length} @ ${effort}: blocked, architect answered`)
+    continue
+  }
+
+  phase('Verify')
+  log(`rung ${rung}/${rungs.length} @ ${effort}: running ${harness.command}`)
+  const verdict = await agent(harnessPrompt(), {
+    agentType: 'harness',
+    effort: 'low',
+    phase: 'Verify',
+    label: `verify ${rung}/${rungs.length}`,
+    schema: VERDICT,
+  })
+  const passed = verdict?.passed === true && verdict.testsWeakened === false
+  attempts.push({ rung, effort, outcome: passed ? 'passed' : 'failed', securityFinding: verdict?.securityFinding ?? '' })
+  log(`rung ${rung} @ ${effort}: ${passed ? 'harness passed' : 'harness failed'}`)
+
+  if (passed) {
+    return {
+      status: 'done',
+      effort,
+      attempts,
+      files: report.files,
+      summary: report.summary,
+      harnessTail: report.harnessTail,
+      contractChanged: verdict.contractChanged,
+      diffStat: verdict.diffStat,
+    }
+  }
+
+  feedback = verdict == null
+    ? 'The harness produced no verdict.'
+    : verdict.testsWeakened
+      ? `A test was deleted, skipped or narrowed. Restore it and make the implementation pass it.\n${verdict.failureExcerpt}`
+      : verdict.failureExcerpt
+  if (verdict?.securityFinding)
+    feedback = `Security invariant failed: ${verdict.securityFinding}\n${feedback}`
+
+  if (rung === rungs.length - 1) {
+    phase('Design')
+    log(`rung ${rung}/${rungs.length} failed twice: architect redesigns before the last rung`)
+    spec = await agent(architectPrompt(`Two rungs have failed the harness. Latest failure:\n${feedback}\n\nDecide whether the approach, the contract or the boundary is wrong before the last attempt.`), {
+      agentType: 'architect',
+      effort: 'xhigh',
+      phase: 'Design',
+      label: 'design before last rung',
+      schema: SPEC,
+    })
+  }
+}
+
+return { status: 'failed', attempts, lastFailure: feedback }

package/templates/ai/cursor/_cursor/rules/construct.mdc

@@ -0,0 +1,19 @@
+---
+description: Construct baseline — where the rules, contract and harness live
+alwaysApply: true
+---
+
+This repository runs on a construct materialized by `mikoshi-construct`. Before changing code read, in
+this order: `architecture/principles.md` (architecture, security, reasoning budget), `AGENTS.md`
+(what the product does, module map, commands, composition roots, dependency policy, high-effort
+areas, defects vs accepted variance), `architecture/security-invariants.md`.
+
+The harness command is in `construct.json` (`harness.command`). A change is done only when it passes.
+API changes start from the contract file named in `construct.json` (`contracts.path`); regenerate the
+types with `pnpm contracts:types` before implementing. Composition models in the directory
+`construct.json` names as `discovery.composition` are the source of the diagrams; edit the model and run
+`pnpm composition:render`, never the rendered block.
+
+Discovery: when asked to "run construct discovery", follow the `construct-discover` rule in this
+directory step by step. It fills every `<!-- construct:discover:* -->` block in AGENTS.md and
+architecture/ with what you verified by reading code.

package/templates/ai/review/_github/workflows/claude-review.yml.eta

@@ -0,0 +1,51 @@
+name: Claude Review
+
+on:
+  pull_request:
+    types: [labeled]
+  workflow_dispatch:
+    inputs:
+      pr:
+        description: Pull request number
+        required: true
+        type: string
+
+concurrency:
+  group: claude-review-${{ github.event.pull_request.number || inputs.pr }}
+  cancel-in-progress: true
+
+jobs:
+  review:
+    if: github.event_name == 'workflow_dispatch' || github.event.label.name == 'claude-review'
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+      id-token: write
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      REPO: ${{ github.repository }}
+      PR_NUMBER: ${{ github.event.pull_request.number || inputs.pr }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Check out the pull request branch
+        run: gh pr checkout "$PR_NUMBER"
+
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.CODE_REVIEW_API_KEY }}
+          plugin_marketplaces: https://github.com/anthropics/claude-code.git
+          plugins: code-review@claude-code-plugins
+          prompt: /code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number || inputs.pr }}
+          claude_args: |
+            --model {{reviewModel}}
+            --allowedTools "Read,Grep,Glob,Bash,Task,Agent,TodoWrite,WebFetch,mcp__github_inline_comment__create_inline_comment"
+
+      - name: Remove trigger label
+        if: always() && github.event_name == 'pull_request'
+        run: gh api -X DELETE "repos/$REPO/issues/$PR_NUMBER/labels/claude-review" --silent || true