maurao-method 0.0.0-stage → 0.1.1

package/.clinerules/maurao-method.md

@@ -0,0 +1,6 @@
+---
+description: Apply the Maurao Method to software engineering work.
+---
+
+Read `AGENTS.md` before working. Use the smallest applicable skill from `skills/` and the relevant technology pack from `technology-packs/`. Keep requirements, implementation, and verification evidence explicit.
+

package/.cursor/rules/maurao-method.mdc

@@ -0,0 +1,7 @@
+---
+description: Apply the Maurao Method to software engineering work in this repository.
+alwaysApply: true
+---
+
+Read `AGENTS.md` before working. Use the smallest applicable skill from `skills/`, and use the relevant technology pack from `technology-packs/`. Keep requirements, implementation, and verification evidence explicit. Do not claim validation that was not executed.
+

package/.github/copilot-instructions.md

@@ -0,0 +1,6 @@
+# Maurao Method instructions
+
+Follow the repository contract in [`AGENTS.md`](../AGENTS.md).
+
+Before changing code, load the relevant skill from `skills/` and the matching technology pack from `technology-packs/` when applicable.
+

package/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Validate package
+        run: npm run validate
+
+      - name: Run CLI tests
+        run: npm test
+
+      - name: Test CLI help and package listing
+        run: |
+          node bin/maurao.mjs help
+          node bin/maurao.mjs list
+
+      - name: Check package contents
+        run: npm pack --dry-run

package/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish npm package
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: npm
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+          package-manager-cache: false
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Validate package
+        run: npm run validate
+
+      - name: Publish with npm trusted publishing
+        run: npm publish

package/.github/workflows/release-on-main.yml

@@ -0,0 +1,86 @@
+name: Release on main
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'AGENTS.md'
+      - 'CLAUDE.md'
+      - 'GEMINI.md'
+      - 'README.md'
+      - '.clinerules/**'
+      - '.cursor/**'
+      - '.github/copilot-instructions.md'
+      - '.maurao/**'
+      - 'bin/**'
+      - 'commands/**'
+      - 'docs/**'
+      - 'skills/**'
+      - 'technology-packs/**'
+      - 'templates/**'
+      - 'package.json'
+      - 'package-lock.json'
+
+permissions:
+  contents: write
+
+concurrency:
+  group: release-on-main
+  cancel-in-progress: false
+
+jobs:
+  release:
+    if: github.actor != 'github-actions[bot]'
+    runs-on: ubuntu-latest
+    environment: npm
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+          package-manager-cache: false
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Validate package
+        run: npm run validate
+
+      - name: Run tests
+        run: npm test
+
+      - name: Increment patch version
+        id: version
+        shell: bash
+        run: |
+          npm version patch --no-git-tag-version
+          VERSION="$(node -p "require('./package.json').version")"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Publish package
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish
+
+      - name: Create release commit and tag
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add package.json package-lock.json
+          git commit -m "chore(release): v${VERSION}"
+          git tag "v${VERSION}"
+          git push origin HEAD:main --follow-tags
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ steps.version.outputs.version }}
+        run: gh release create "v${VERSION}" --title "v${VERSION}" --generate-notes

package/.maurao/README.md

@@ -0,0 +1,13 @@
+# Maurao project artifacts
+
+This directory stores the durable artifacts produced by the Maurao Method for the host project.
+
+- `product-brief.md`: product problem, users, outcome, and smallest useful slice.
+- `system-context.md`: current system, boundaries, dependencies, and invariants.
+- `technology-inventory.md`: detected technology and confirmed commands.
+- `specifications/`: approved change specifications.
+- `decisions/`: architecture and product decisions.
+- `plans/`: implementation plans.
+- `reports/`: verification, spike, review, and release reports.
+
+Artifacts are evidence and decision records. They should evolve with the product and must not claim checks that were not executed.

package/.maurao/config.json

@@ -0,0 +1,17 @@
+{
+  "method": "maurao-method",
+  "version": "0.1",
+  "projectMode": "auto",
+  "rigor": "adaptive",
+  "technologyDiscovery": "required",
+  "artifacts": {
+    "root": ".maurao",
+    "productBrief": ".maurao/product-brief.md",
+    "systemContext": ".maurao/system-context.md",
+    "technologyInventory": ".maurao/technology-inventory.md",
+    "specifications": ".maurao/specifications",
+    "decisions": ".maurao/decisions",
+    "plans": ".maurao/plans",
+    "reports": ".maurao/reports"
+  }
+}

package/AGENTS.md

@@ -0,0 +1,30 @@
+# Maurao Method
+
+This repository defines a portable, specification-driven engineering method for AI coding agents.
+
+## Repository contract
+
+- Read the relevant skill before executing a workflow.
+- Start with `technology-discovery` when the project stack, runtime, or validation commands are unknown.
+- Classify work as greenfield, brownfield, or hybrid before choosing a workflow.
+- Select rigor L0–L3 from `docs/workflow.md` based on ambiguity, blast radius, and risk.
+- Keep the core technology-agnostic; put stack-specific behavior in `technology-packs/`.
+- Treat `templates/` as normative starting points, not mandatory ceremony for trivial changes.
+- Use `.maurao/` as the durable artifact root when working in a host project; follow `docs/artifact-contract.md`.
+- Every implementation must have an explicit verification outcome.
+- Never claim a command, test, review, or deployment was performed unless it was actually performed.
+- Preserve user changes and do not create commits unless explicitly requested.
+
+## Skill discovery
+
+The canonical skills live under `skills/`. Use the smallest composition that covers the task:
+
+- `skills/core/` — reasoning and lifecycle skills.
+- `skills/practices/` — testing, observability, review, and delivery practices.
+- `skills/workflows/` — end-to-end work modes.
+- `technology-packs/` — Node.js, .NET, and Python guidance.
+- `commands/` — tool-independent command entry points.
+- `.maurao/` — host-project configuration and durable engineering artifacts.
+
+Tool-specific entry points may point here, but must not duplicate the method.
+

package/CLAUDE.md

@@ -0,0 +1,6 @@
+# Maurao Method
+
+Read and follow the repository contract in [`AGENTS.md`](AGENTS.md).
+
+Canonical skills are under `skills/`. Load only the skill relevant to the current task and its required references.
+

package/GEMINI.md

@@ -0,0 +1,6 @@
+# Maurao Method
+
+Read and follow the repository contract in [`AGENTS.md`](AGENTS.md).
+
+Canonical skills are under `skills/`. Load only the skill relevant to the current task and its required references.
+

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# Maurao Method
+
+## Modular engineering for AI-assisted software development
+
+Maurao Method is a technology-agnostic engineering method for building reliable software with AI agents.
+
+It combines specification-driven development with disciplined implementation, testing, observability, debugging, review, and verifiable delivery evidence.
+
+## Principles
+
+- Understand the problem before changing the code.
+- Treat specifications and acceptance criteria as shared contracts.
+- Prefer the smallest safe change that satisfies the contract.
+- Make tests, observability, and review part of implementation—not afterthoughts.
+- Report evidence separately from assumptions.
+- Keep the core generic and move technology-specific knowledge into focused skills.
+
+## Repository structure
+
+```text
+skills/
+├── core/                  # Technology-agnostic engineering capabilities
+├── practices/             # Reusable engineering practices
+├── technology-packs/      # Node.js, .NET, Python, and other stacks
+└── workflows/             # Composable end-to-end work modes
+commands/                  # Tool-independent command entry points
+templates/                 # Specifications, plans, tests, reviews, and reports
+docs/                      # Method documentation and design decisions
+```
+
+## Initial skills
+
+- `core/specification`: define intent, behavior, constraints, and acceptance criteria.
+- `core/debugging`: reproduce failures, test hypotheses, identify root cause, and prevent regression.
+- `core/spike`: answer technical questions through bounded experiments and recorded evidence.
+- `core/architecture`: make proportionate architecture decisions.
+- `core/project-discovery`: establish a baseline for greenfield, brownfield, and hybrid projects.
+- `core/technology-discovery`: detect the real stack and select applicable technology packs.
+- `core/product-discovery`: frame new product problems and the smallest useful slice.
+- `core/requirements`: structure functional and non-functional requirements.
+- `core/planning`: create ordered, verifiable implementation tasks.
+- `practices/testing`: design tests from behavior and preserve regression coverage.
+- `practices/observability`: define useful logs, metrics, traces, and operational signals.
+- `practices/code-review`: review correctness, risk, security, and maintainability.
+- `practices/pull-request`: prepare focused, evidence-based pull requests.
+- `practices/verification`: map acceptance criteria to executed evidence.
+- `practices/security`: analyze security, privacy, abuse, and supply-chain risks.
+- `practices/data-migration`: plan safe schema and data changes.
+- `practices/release-readiness`: decide whether a change can be delivered safely.
+- `workflows/feature-development`: compose the core loop for a production change.
+- `workflows/bug-fix`: diagnose and fix defects with regression protection.
+- `workflows/greenfield-product`: create a new product through a validated vertical slice.
+- `workflows/brownfield-change`: safely change an existing product.
+
+## Portability
+
+The method uses a canonical `AGENTS.md`, portable `SKILL.md` files, tool-independent commands, and thin adapters for Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI, and Cline. Run `scripts/install.ps1` from PowerShell to install the method into another project without overwriting existing files unless `-Force` is supplied.
+
+The canonical structure is independent of a model provider, editor, CLI, or programming language. Technology packs provide focused guidance for Node.js, .NET, Python, and Java.
+
+Validate the repository and installer with:
+
+```powershell
+.\scripts\validate.ps1 -TestInstaller
+```
+
+See [tool support](docs/tool-support.md) for the distinction between GPT as a model and Codex as the coding-agent environment.
+
+## npm CLI
+
+When published, the recommended installation will be:
+
+```powershell
+npm install -g maurao-method
+maurao init . --tool all
+```
+
+Available commands:
+
+```text
+maurao init [directory]   Install the method in a project
+maurao validate           Validate the packaged skills and required files
+maurao list               List commands and skills
+maurao doctor [directory] Check whether a project is installed correctly
+maurao inspect [directory] Detect technology evidence and write the inventory
+```
+
+The npm CI/CD setup is documented in [docs/npm-release.md](docs/npm-release.md). Pull requests run validation automatically, and package changes merged into `main` create a patch release, npm publication, version tag, and GitHub Release.
+
+## Status
+
+Early development. The method and skill contracts are expected to evolve before the first stable release.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/bin/maurao.mjs

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+
+import { existsSync, cpSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(fileURLToPath(new URL('..', import.meta.url)));
+const commonEntries = [
+  'AGENTS.md',
+  '.maurao',
+  'commands',
+  'docs',
+  'skills',
+  'technology-packs',
+  'templates'
+];
+
+const adapters = {
+  codex: ['AGENTS.md'],
+  claude: ['CLAUDE.md', '.claude-skills'],
+  cursor: ['.cursor'],
+  copilot: ['.github/copilot-instructions.md', '.agents-skills'],
+  gemini: ['GEMINI.md'],
+  cline: ['.clinerules']
+};
+
+function usage() {
+  console.log(`Maurao Method CLI
+
+Usage:
+  maurao init [directory] [--tool all|codex|claude|cursor|copilot|gemini|cline] [--force]
+  maurao validate
+  maurao list
+  maurao doctor [directory]
+  maurao inspect [directory]
+  maurao help
+
+Examples:
+  maurao init .
+  maurao init C:\\projects\\my-app --tool codex
+  maurao init . --tool all --force
+`);
+}
+
+function parseOptions(args) {
+  const options = { force: false, tool: 'all', positional: [] };
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    if (value === '--force') options.force = true;
+    else if (value === '--tool') options.tool = args[++index] ?? '';
+    else if (value === '--help' || value === '-h') options.help = true;
+    else options.positional.push(value);
+  }
+  return options;
+}
+
+function copyEntry(sourceRelative, targetRoot, force) {
+  const source = join(packageRoot, sourceRelative);
+  const destination = join(targetRoot, sourceRelative);
+  if (!existsSync(source)) throw new Error(`Package entry not found: ${sourceRelative}`);
+  if (existsSync(destination) && !force) {
+    console.log(`Skipped existing path: ${destination}`);
+    return;
+  }
+  mkdirSync(dirname(destination), { recursive: true });
+  cpSync(source, destination, { recursive: true, force });
+  console.log(`Installed: ${destination}`);
+}
+
+function copyAdapter(adapter, targetRoot, force) {
+  for (const entry of adapters[adapter]) {
+    if (entry === '.claude-skills') {
+      copyEntry('skills', targetRoot + '/.claude', force);
+    } else if (entry === '.agents-skills') {
+      copyEntry('skills', targetRoot + '/.agents', force);
+    } else {
+      copyEntry(entry, targetRoot, force);
+    }
+  }
+}
+
+function init(args) {
+  const options = parseOptions(args);
+  if (options.help) return usage();
+  const allowedTools = ['all', ...Object.keys(adapters)];
+  if (!allowedTools.includes(options.tool)) throw new Error(`Invalid tool. Use: ${allowedTools.join(', ')}`);
+  const targetRoot = resolve(options.positional[0] ?? '.');
+  mkdirSync(targetRoot, { recursive: true });
+  for (const entry of commonEntries) copyEntry(entry, targetRoot, options.force);
+  const selected = options.tool === 'all' ? Object.keys(adapters) : [options.tool];
+  for (const adapter of selected) copyAdapter(adapter, targetRoot, options.force);
+  console.log(`Maurao Method installed in ${targetRoot}`);
+}
+
+function list() {
+  const skills = [];
+  for (const category of readdirSync(join(packageRoot, 'skills'))) {
+    const categoryPath = join(packageRoot, 'skills', category);
+    if (!existsSync(categoryPath)) continue;
+    for (const skill of readdirSync(categoryPath)) {
+      if (existsSync(join(categoryPath, skill, 'SKILL.md'))) skills.push(`${category}/${skill}`);
+    }
+  }
+  console.log('Commands:');
+  for (const command of readdirSync(join(packageRoot, 'commands')).filter((entry) => entry.endsWith('.md'))) {
+    console.log(`  maurao ${command.replace(/\.md$/, '')}`);
+  }
+  console.log('\nSkills:');
+  for (const skill of skills.sort()) console.log(`  ${skill}`);
+}
+
+function validate() {
+  const skillsRoot = join(packageRoot, 'skills');
+  const skills = [];
+  for (const category of readdirSync(skillsRoot)) {
+    const categoryPath = join(skillsRoot, category);
+    for (const skill of readdirSync(categoryPath)) {
+      const file = join(categoryPath, skill, 'SKILL.md');
+      if (!existsSync(file)) continue;
+      const content = readFileSync(file, 'utf8');
+      if (!/^---\s*\nname: .+\ndescription: .+\n---/s.test(content)) {
+        throw new Error(`Invalid skill frontmatter: ${file}`);
+      }
+      skills.push(skill);
+    }
+  }
+  if (new Set(skills).size !== skills.length) throw new Error('Duplicate skill directory name detected');
+  for (const required of ['AGENTS.md', 'templates/feature-spec.md', 'technology-packs/java/README.md']) {
+    if (!existsSync(join(packageRoot, required))) throw new Error(`Missing required entry: ${required}`);
+  }
+  console.log(`Validation passed: ${skills.length} skills.`);
+}
+
+function doctor(args) {
+  const targetRoot = resolve(args[0] ?? '.');
+  const checks = ['AGENTS.md', '.maurao/config.json', 'skills', 'technology-packs', 'templates', 'commands'];
+  const missing = checks.filter((entry) => !existsSync(join(targetRoot, entry)));
+  if (missing.length > 0) {
+    console.error(`Maurao Method is not installed correctly in ${targetRoot}`);
+    for (const entry of missing) console.error(`Missing: ${entry}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`Maurao Method is installed in ${targetRoot}`);
+}
+
+const ignoredDirectories = new Set(['.git', '.maurao', 'node_modules', 'target', 'build', 'dist', '.venv', 'venv', '__pycache__']);
+const evidence = [
+  ['package.json', 'Node.js', 'package manifest'],
+  ['tsconfig.json', 'TypeScript', 'TypeScript configuration'],
+  ['pom.xml', 'Java / Maven', 'Maven build descriptor'],
+  ['build.gradle', 'Java or Kotlin / Gradle', 'Gradle build descriptor'],
+  ['build.gradle.kts', 'Kotlin or Java / Gradle', 'Kotlin Gradle build descriptor'],
+  ['gradlew', 'Java or Kotlin / Gradle', 'Gradle wrapper'],
+  ['pyproject.toml', 'Python', 'Python project manifest'],
+  ['requirements.txt', 'Python', 'Python dependency file'],
+  ['go.mod', 'Go', 'Go module manifest'],
+  ['Cargo.toml', 'Rust', 'Cargo manifest'],
+  ['composer.json', 'PHP', 'Composer manifest'],
+  ['Gemfile', 'Ruby', 'Ruby dependency manifest'],
+  ['Package.swift', 'Swift', 'Swift package manifest']
+];
+
+function walkFiles(root, depth = 0, result = []) {
+  if (depth > 3) return result;
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (entry.isDirectory() && !ignoredDirectories.has(entry.name)) {
+      walkFiles(join(root, entry.name), depth + 1, result);
+    } else if (entry.isFile()) {
+      result.push(join(root, entry.name));
+    }
+  }
+  return result;
+}
+
+function inspect(args) {
+  const targetRoot = resolve(args[0] ?? '.');
+  if (!existsSync(targetRoot) || !statSync(targetRoot).isDirectory()) throw new Error(`Directory not found: ${targetRoot}`);
+  const files = walkFiles(targetRoot);
+  const findings = [];
+  for (const [fileName, technology, reason] of evidence) {
+    const matches = files.filter((file) => file.endsWith(`\\${fileName}`) || file.endsWith(`/${fileName}`));
+    if (matches.length > 0) findings.push({ technology, reason, files: matches.map((file) => file.slice(targetRoot.length + 1)) });
+  }
+  const lines = [
+    '# Technology Inventory',
+    '',
+    `- Project: ${targetRoot}`,
+    '- Mode: To be classified as greenfield, brownfield, or hybrid',
+    '',
+    '## Detected technologies',
+    '',
+    '| Technology | Evidence | Confidence |',
+    '|---|---|---|'
+  ];
+  if (findings.length === 0) lines.push('| No known technology detected | Inspect repository manually | Low |');
+  for (const finding of findings) lines.push(`| ${finding.technology} | ${finding.reason}: ${finding.files.join(', ')} | Medium |`);
+  lines.push('', '## Commands to confirm', '', '| Purpose | Command | Confirmed? |', '|---|---|---|', '| Install | | No |', '| Run | | No |', '| Test | | No |', '| Lint | | No |', '| Build | | No |', '', '## Unknowns', '', '- Confirm versions, active modules, and project-specific commands before implementation.');
+  const artifactRoot = join(targetRoot, '.maurao');
+  mkdirSync(artifactRoot, { recursive: true });
+  const output = join(artifactRoot, 'technology-inventory.md');
+  writeFileSync(output, `${lines.join('\n')}\n`, 'utf8');
+  console.log(`Technology inventory written to ${output}`);
+  for (const finding of findings) console.log(`Detected: ${finding.technology}`);
+}
+
+const [command = 'help', ...args] = process.argv.slice(2);
+try {
+  if (command === 'init') init(args);
+  else if (command === 'validate') validate();
+  else if (command === 'list') list();
+  else if (command === 'doctor') doctor(args);
+  else if (command === 'inspect') inspect(args);
+  else usage();
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = 1;
+}

package/commands/debug.md

@@ -0,0 +1,4 @@
+# maurao debug
+
+Load `skills/core/debugging`, `skills/practices/testing`, and `skills/practices/observability` when relevant. Reproduce, hypothesize, collect evidence, identify root cause, apply the smallest fix, and verify regression protection.
+

package/commands/discover.md

@@ -0,0 +1,4 @@
+# maurao discover
+
+Load `skills/core/project-discovery`, `skills/core/technology-discovery`, and `skills/core/product-discovery` when the request concerns a new product. Determine greenfield, brownfield, or hybrid mode, then create the appropriate baseline artifacts.
+

package/commands/map.md

@@ -0,0 +1,4 @@
+# maurao map
+
+Load `skills/core/project-discovery`, `skills/core/technology-discovery`, and `skills/core/brownfield-analysis`. Inspect the existing product before proposing a change and create `templates/brownfield-map.md` from repository evidence.
+

package/commands/plan.md

@@ -0,0 +1,4 @@
+# maurao plan
+
+Load `skills/core/planning`, `skills/core/architecture`, and the active technology pack. Convert an approved specification into ordered tasks with dependencies and independent completion evidence.
+

package/commands/pr.md

@@ -0,0 +1,4 @@
+# maurao pr
+
+Load `skills/practices/pull-request` and `templates/pull-request.md`. Prepare a focused, reviewable pull request with exact validation evidence, risks, rollout, rollback, and reviewer focus.
+

package/commands/review.md

@@ -0,0 +1,4 @@
+# maurao review
+
+Load `skills/practices/code-review`. Review the complete change against the specification, surrounding code, risk boundaries, tests, security, observability, and maintainability. Report findings by severity.
+

package/commands/specify.md

@@ -0,0 +1,4 @@
+# maurao specify
+
+Load `skills/core/specification` and `skills/core/requirements`. Create or refine a specification with requirements, acceptance criteria, risks, non-goals, and a verification plan.
+

package/commands/spike.md

@@ -0,0 +1,4 @@
+# maurao spike
+
+Load `skills/core/spike` and the relevant technology pack. Run a bounded experiment, record evidence and limitations, and produce a decision or an explicit inconclusive result.
+

package/commands/verify.md

@@ -0,0 +1,4 @@
+# maurao verify
+
+Load `skills/practices/verification`, `skills/practices/testing`, and `skills/practices/release-readiness` when delivery is involved. Map every acceptance criterion to actual evidence and classify unexecuted checks honestly.
+

package/docs/artifact-contract.md

@@ -0,0 +1,22 @@
+# Artifact contract
+
+The project-local `.maurao/` directory is the durable state of the method. Tool adapters and chat history are transport layers; they are not the source of truth.
+
+## Required artifacts by depth
+
+| Depth | Required artifacts |
+|---|---|
+| L0 | Verification note in the final response |
+| L1 | Specification, implementation plan, test plan, verification report |
+| L2 | System context, change proposal, decision records, test plan, observability plan, verification report |
+| L3 | Product brief, system context, technology inventory, requirements, architecture decisions, delivery increments, threat model, verification and release reports |
+
+## Naming
+
+- Specifications: `.maurao/specifications/<change-id>.md`
+- Decisions: `.maurao/decisions/ADR-<number>-<slug>.md`
+- Plans: `.maurao/plans/<change-id>.md`
+- Reports: `.maurao/reports/<change-id>-<report-type>.md`
+
+Use stable IDs such as `REQ-001`, `AC-001`, `TASK-001`, `TEST-001`, and `THR-001` to preserve traceability.
+