chipgraph 0.1.0rc1__tar.gz

chipgraph-0.1.0rc1/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "chipgraph",
+  "description": "chipgraph: an AI agent system for chip (IC) design",
+  "owner": {
+    "name": "quynhonsemiconductor",
+    "url": "https://github.com/quynhonsemiconductor"
+  },
+  "plugins": [
+    {
+      "name": "chipgraph",
+      "source": "./plugin",
+      "description": "chipgraph for chip (IC) design in Claude Code: /chipgraph:status, /chipgraph:trace, /chipgraph:ask, /chipgraph:triage, /chipgraph:init-chipgraph and /chipgraph:run, over the chipgraph MCP server."
+    }
+  ]
+}

chipgraph-0.1.0rc1/.dockerignore

@@ -0,0 +1,29 @@
+# Root .dockerignore — the build context is the repo root (docker/Dockerfile COPYs
+# pyproject.toml, uv.lock, README.md, src/, and, for the `test` target, tests/ and
+# examples/ from there), so this lives at the root rather than under docker/.
+
+.git
+.github
+.venv
+venv
+__pycache__
+*.py[cod]
+*.egg-info
+.eggs
+.mypy_cache
+.ruff_cache
+.pytest_cache
+.cache
+dist
+build
+docs
+doc
+plugin
+.claude-plugin
+evals
+interfaces
+presets
+orgs
+*.md
+!README.md
+.DS_Store

chipgraph-0.1.0rc1/.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,json,toml,md}]
+indent_style = space
+indent_size = 2

chipgraph-0.1.0rc1/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @Nghia-VanTrong

chipgraph-0.1.0rc1/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.13", "3.14"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: ${{ matrix.python }}
+
+      - run: uv sync --locked
+
+      - run: uv run ruff check .
+
+      - run: uv run ruff format --check .
+
+      - run: uv run lint-imports
+
+      - run: uv run mypy
+
+      - run: uv run pytest
+
+      - run: make schemas-check
+
+  secrets:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+      - uses: trufflesecurity/trufflehog@4dd8831c5f12599465d4d45c3c447b4018a34c85 # v3.97.9
+        with:
+          extra_args: --only-verified

chipgraph-0.1.0rc1/.github/workflows/evals.yml

@@ -0,0 +1,132 @@
+name: evals
+
+# Real-model evals (task M1-17): `chipgraph eval` with runtime claude-code (headless
+# Claude Code, haiku main session by default) on the ask, triage, triage-holdout and
+# triage-holdout2 suites. Never on push or pull requests: started by hand or weekly. The
+# framework itself is checked on every PR by the fake-runtime tests in the normal CI
+# (tests/evals).
+#
+# Auth: the repository secret CHIPGRAPH_EVALS_CLAUDE_TOKEN, a Claude Code OAuth token of
+# a separate account (`claude setup-token`), passed to `claude` as
+# CLAUDE_CODE_OAUTH_TOKEN. Without the secret the job skips, green, with a notice.
+# Cost cap: --budget-usd per suite (claude's --max-budget-usd per sample, and the suite
+# stops once the summed total_cost_usd reaches it); --time-limit per suite.
+
+on:
+  workflow_dispatch:
+    inputs:
+      suite:
+        description: Suite to run
+        type: choice
+        options: [all, ask, triage, triage-holdout, triage-holdout2]
+        default: all
+      main_model:
+        description: Main session model
+        type: string
+        default: haiku
+      budget_usd:
+        description: Cost cap per suite, in USD
+        type: string
+        default: "3"
+  schedule:
+    - cron: "17 3 * * 1" # Mondays 03:17 UTC
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: false
+
+env:
+  CLAUDE_CODE_VERSION: 2.1.286
+
+jobs:
+  evals:
+    runs-on: ubuntu-latest
+    timeout-minutes: 240
+    steps:
+      - name: Check for the evals secret
+        id: auth
+        env:
+          TOKEN: ${{ secrets.CHIPGRAPH_EVALS_CLAUDE_TOKEN }}
+        run: |
+          if [ -n "$TOKEN" ]; then
+            echo "ok=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "ok=false" >> "$GITHUB_OUTPUT"
+            msg="CHIPGRAPH_EVALS_CLAUDE_TOKEN is not set: real-model evals skipped (see evals/README.md)."
+            echo "::notice::$msg"
+            echo "$msg" >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        if: steps.auth.outputs.ok == 'true'
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        if: steps.auth.outputs.ok == 'true'
+        with:
+          python-version: "3.14"
+
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        if: steps.auth.outputs.ok == 'true'
+        with:
+          node-version: "24"
+
+      - name: Install Claude Code
+        if: steps.auth.outputs.ok == 'true'
+        run: |
+          npm install -g "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}"
+          claude --version
+
+      - run: uv sync --locked
+        if: steps.auth.outputs.ok == 'true'
+
+      - name: Run the evals
+        id: run
+        if: steps.auth.outputs.ok == 'true'
+        env:
+          CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CHIPGRAPH_EVALS_CLAUDE_TOKEN }}
+          SUITE: ${{ inputs.suite || 'all' }}
+          MAIN_MODEL: ${{ inputs.main_model || 'haiku' }}
+          BUDGET_USD: ${{ inputs.budget_usd || '3' }}
+          EVAL_OUT: ${{ runner.temp }}/eval-report
+        run: |
+          set -u
+          if [ "$SUITE" = all ]; then suites="ask triage triage-holdout triage-holdout2"; else suites="$SUITE"; fi
+          mkdir -p "$EVAL_OUT"
+          failed=""
+          for suite in $suites; do
+            echo "::group::chipgraph eval $suite"
+            rc=0
+            uv run chipgraph eval "$suite" --runtime claude-code \
+              --main-model "$MAIN_MODEL" --budget-usd "$BUDGET_USD" \
+              --out "$EVAL_OUT/$suite" || rc=$?
+            echo "::endgroup::"
+            if [ -f "$EVAL_OUT/$suite/summary.md" ]; then
+              cat "$EVAL_OUT/$suite/summary.md" >> "$GITHUB_STEP_SUMMARY"
+            else
+              echo "chipgraph eval $suite: no report (exit $rc)" >> "$GITHUB_STEP_SUMMARY"
+            fi
+            [ "$rc" -eq 0 ] || failed="$failed $suite"
+          done
+          echo "failed=$failed" >> "$GITHUB_OUTPUT"
+
+      - name: Upload the eval report
+        if: always() && steps.auth.outputs.ok == 'true'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: eval-report-${{ github.run_id }}
+          path: ${{ runner.temp }}/eval-report
+          if-no-files-found: error
+          retention-days: 90
+
+      - name: Fail if a suite failed
+        if: steps.auth.outputs.ok == 'true' && steps.run.outputs.failed != ''
+        env:
+          FAILED: ${{ steps.run.outputs.failed }}
+        run: |
+          echo "::error::eval suites failed:$FAILED"
+          exit 1

chipgraph-0.1.0rc1/.github/workflows/image.yml

@@ -0,0 +1,142 @@
+name: image
+
+on:
+  pull_request:
+    paths:
+      - docker/**
+      - pyproject.toml
+      - uv.lock
+      - src/**
+      - tests/e2e/**
+      - examples/**
+      - .github/workflows/image.yml
+  push:
+    branches: [main]
+    tags: ["v*"]
+    paths:
+      - docker/**
+      - pyproject.toml
+      - uv.lock
+      - src/**
+      - tests/e2e/**
+      - examples/**
+      - .github/workflows/image.yml
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  IMAGE: ghcr.io/quynhonsemiconductor/chipgraph-eda
+
+jobs:
+  build-test:
+    name: build test image, run tinysoc e2e
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
+
+      - uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
+        with:
+          context: .
+          file: docker/Dockerfile
+          target: test
+          tags: chipgraph-eda:test
+          load: true
+          push: false
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Run the tinysoc e2e suite inside the image
+        env:
+          REPORT_DIR: ${{ runner.temp }}/e2e-report
+        run: |
+          set -eu
+          mkdir -p "$REPORT_DIR"
+          docker run --rm \
+            -v "$REPORT_DIR:/tmp/report" \
+            chipgraph-eda:test \
+            sh -c 'uv run --no-sync pytest -m e2e tests/e2e -q --junitxml=/tmp/report/e2e-junit.xml'
+
+      - name: Fail if the e2e tests did not actually run
+        env:
+          REPORT_DIR: ${{ runner.temp }}/e2e-report
+        run: |
+          python3 - "$REPORT_DIR/e2e-junit.xml" <<'PY'
+          import sys
+          import xml.etree.ElementTree as ET
+
+          root = ET.parse(sys.argv[1]).getroot()
+          suite = root if root.tag == "testsuite" else root.find("testsuite")
+          if suite is None:
+              raise SystemExit("no <testsuite> found in the junit report")
+
+          tests = int(suite.get("tests", 0))
+          failures = int(suite.get("failures", 0))
+          errors = int(suite.get("errors", 0))
+          skipped = int(suite.get("skipped", 0))
+          passed = tests - failures - errors - skipped
+
+          print(f"tests={tests} passed={passed} failures={failures} errors={errors} skipped={skipped}")
+
+          if skipped:
+              raise SystemExit(
+                  f"{skipped} e2e test(s) were skipped inside the image "
+                  "(verilator/make missing?) — the image must run them, not skip them"
+              )
+          if failures or errors:
+              raise SystemExit("e2e tests failed inside the image")
+          if passed < 5:
+              raise SystemExit(f"expected at least 5 passing e2e tests, got {passed}")
+          PY
+
+  publish:
+    name: publish image to GHCR
+    needs: build-test
+    if: >-
+      github.event_name == 'push' &&
+      (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write # push chipgraph-eda to ghcr.io
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
+
+      - id: meta
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
+        with:
+          images: ${{ env.IMAGE }}
+          tags: |
+            type=raw,value=main,enable={{is_default_branch}}
+            type=sha,prefix=sha-,format=short
+            type=semver,pattern={{version}}
+
+      - uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
+        with:
+          context: .
+          file: docker/Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

chipgraph-0.1.0rc1/.github/workflows/release.yml

@@ -0,0 +1,128 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Where to publish"
+        required: true
+        type: choice
+        options: ["testpypi", "pypi"]
+        default: "testpypi"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: "3.13"
+
+      - name: Check that the tag matches pyproject.toml's version
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version="$(uv run --no-project python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          if [ "$tag" != "$version" ]; then
+            echo "::error::tag v$tag does not match pyproject.toml version $version"
+            exit 1
+          fi
+
+      - name: Read the version
+        id: version
+        run: |
+          version="$(uv run --no-project python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - run: uv build
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    needs: build
+    if: |
+      (startsWith(github.ref, 'refs/tags/') && contains(github.ref_name, 'rc')) ||
+      (github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi')
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  # A release candidate goes to TestPyPI first; this job installs that exact build from
+  # TestPyPI and runs it. Only if it works does the same build go on to PyPI, because the
+  # marketplace plugin runs `uvx chipgraph@<version>`, which resolves from PyPI.
+  smoke-testpypi:
+    needs: [build, publish-testpypi]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: "3.13"
+
+      - name: Install the TestPyPI build with uvx and run it
+        env:
+          VERSION: ${{ needs.build.outputs.version }}
+        run: |
+          # TestPyPI can take a minute to serve a new upload: retry for up to ~5 minutes.
+          for attempt in 1 2 3 4 5 6 7 8 9 10; do
+            if out="$(uvx --no-cache --index https://test.pypi.org/simple/ \
+                --index-strategy unsafe-best-match "chipgraph@$VERSION" --version 2>&1)"; then
+              echo "$out"
+              case "$out" in
+                *"$VERSION"*) ;;
+                *) echo "::error::expected version $VERSION, got: $out"; exit 1 ;;
+              esac
+              uvx --no-cache --index https://test.pypi.org/simple/ \
+                --index-strategy unsafe-best-match "chipgraph@$VERSION" --help > /dev/null
+              exit 0
+            fi
+            echo "attempt $attempt: not installable yet"; sleep 30
+          done
+          echo "::error::chipgraph $VERSION could not be installed from TestPyPI"
+          exit 1
+
+  # A final tag goes straight to PyPI; a release-candidate tag only after the TestPyPI
+  # smoke test passed. Either way the `pypi` environment's reviewer must approve.
+  publish-pypi:
+    needs: [build, smoke-testpypi]
+    if: |
+      !cancelled() && needs.build.result == 'success' && (
+        (startsWith(github.ref, 'refs/tags/') && !contains(github.ref_name, 'rc')) ||
+        (startsWith(github.ref, 'refs/tags/') && contains(github.ref_name, 'rc') &&
+          needs.smoke-testpypi.result == 'success') ||
+        (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+      )
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

chipgraph-0.1.0rc1/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# uv / venv
+.venv/
+venv/
+
+# Caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.cache/
+
+# chipgraph runtime state
+.chipgraph/state/
+
+# OS
+.DS_Store

chipgraph-0.1.0rc1/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.9
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format

chipgraph-0.1.0rc1/.python-version

@@ -0,0 +1 @@
+3.14

chipgraph-0.1.0rc1/AGENTS.md

@@ -0,0 +1,68 @@
+# AGENTS.md — working on the chipgraph repository
+
+`chipgraph` is an AI agent system for chip (IC) design. It treats a chip project as a
+**build graph**: specs, RTL, tests and reports are artifacts; rules produce them (code,
+AI agents or humans); deterministic EDA checks verify every step; humans approve at gates.
+All of this runs over a typed **Design Model** of the chip.
+
+This file tells coding agents (and humans) how to work on this repository.
+
+## Read first, in this order
+
+1. [`docs/IMPLEMENTATION_PLAN.md`](docs/IMPLEMENTATION_PLAN.md): find your task ID, its `depends`, `writes` and `accept`.
+2. [`DESIGN.md`](DESIGN.md): the section your task refers to. It is written in Vietnamese; identifiers are English.
+3. [`docs/DECISIONS.md`](docs/DECISIONS.md): the reasons behind the design. Do not re-litigate a decision in code; propose an ADR instead.
+
+## Hard rules
+
+1. **One task, one PR.** Branch `feat/<task-id>-<slug>`, for example `feat/m0-06-graph`. Take a task only when every `depends` is merged.
+2. **Stay inside `writes`.** If you need to change another file, open an issue and stop.
+3. **Contracts are frozen.** Do not change `src/chipgraph/core/contracts/` or `src/chipgraph/core/plugin_api/` unless your task says so. Other agents build against them.
+4. **Core knows nothing about chips or tools.** `chipgraph.core` must not import `chipgraph.adapters` or any pack, and must not contain project, bus, PDK or tool names (QSoC, APB, GF180, Verilator). `import-linter` enforces the import rule in CI.
+5. **Tests for every `accept` criterion.** CI never calls a real model: use `adapters/llm/fake.py`. Real-model evals run only in the nightly `evals` job.
+6. **Public repository.** Never commit secrets, API keys, internal or NDA data, or files from private projects. Examples and fixtures use open-source IP and PDKs only (`examples/tinysoc`, GF180, Sky130).
+7. **Nothing from the teacher's flow.** Do not copy files, prompts or code from `VLSIT_RTL_Generator_AI_Model`. chipgraph is independent.
+8. **Commits and PRs** use Conventional Commits (`feat:`, `fix:`, `docs:`, `test:`, `chore:`). Do not add AI attribution lines ("Co-Authored-By", "Generated with …") to commits or PR descriptions.
+
+## Commands
+
+```bash
+uv sync                       # install (Python 3.14; 3.13 supported)
+uv run chipgraph --help       # CLI
+uv run pytest                 # all tests
+uv run pytest tests/e2e       # end-to-end on examples/tinysoc (needs the EDA tools or the chipgraph-eda image)
+uv run ruff check . && uv run ruff format --check .
+uv run mypy src/chipgraph/core
+uv run lint-imports           # dependency rules
+make schemas                  # regenerate schemas/ from the pydantic contracts
+```
+
+## Layout
+
+```
+src/chipgraph/core/        contracts, engine, model, runtime, state, config, plugin_api
+src/chipgraph/adapters/    tool, parser, format, llm, runtime, runner, vcs, review
+src/chipgraph/checks/      built-in checks
+src/chipgraph/cli/  mcp/   user surfaces
+src/chipgraph/packs/       built-in packs: pack.yml + code, one snake_case dir each (D36)
+src/chipgraph/orgs/  presets/  interfaces/    built-in data, not code
+plugin/                    Claude Code plugin
+examples/tinysoc/          open-source sample project for end-to-end tests
+evals/                     Inspect AI evals
+docs/                      plan, decisions, research, spikes, pilots
+```
+
+## Code style
+
+- Modern typing (PEP 604 unions, PEP 695 generics). `mypy --strict` for `core/`.
+- Data models are pydantic v2 with a `schema_version` field. Data files (rules, packs, profiles) have a JSON Schema in `schemas/`.
+- Async I/O with `asyncio`. Subprocesses go through a `Runner`, never direct `subprocess` calls in core.
+- Every adapter returns the shared result schema (`CheckResult`, `AgentResult` …), never raw logs.
+- Names: packs, rules, checks, roles and skills are `lower_snake_case` with a namespace, `<pack>/<name>`.
+- Code, comments and docstrings in English.
+
+## Definition of done
+
+See `docs/IMPLEMENTATION_PLAN.md`, section 10. In short: only `writes` touched, tests for
+every `accept`, CI green, docs updated, no secrets, and a PR description with the task ID,
+what changed, how it was verified and remaining risks.

chipgraph-0.1.0rc1/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

chipgraph-0.1.0rc1/CONTRIBUTING.md

@@ -0,0 +1,17 @@
+# Contributing
+
+Work is organized as tasks in [`docs/IMPLEMENTATION_PLAN.md`](docs/IMPLEMENTATION_PLAN.md),
+each with an ID, `depends`, `writes` and `accept` criteria. The working rules are in
+[`AGENTS.md`](AGENTS.md) — read it before opening a PR.
+
+In short:
+
+- Pick a task whose `depends` are already merged. Only touch files in its `writes`.
+- One task, one PR. Branch name: `feat/<task-id>-<slug>` (e.g. `feat/m0-06-graph`).
+- Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/)
+  (`feat:`, `fix:`, `docs:`, `test:`, `chore:`).
+- Run `make check` (lint, type, test) before pushing.
+- Do not add AI attribution lines ("Co-Authored-By", "Generated with …") to commits or
+  PR descriptions.
+- A PR description names the task ID, what changed, how it was verified, and remaining
+  risks.