Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
107 changes: 107 additions & 0 deletions .coding-scaffold/sessions/2026-09-19-agentic-change.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
<!--
Session trace generated by `coding-scaffold session init`. Edit this file as you work — or have
the agent edit it. The structured fields below are read by `coding-scaffold session summarize`.

Sections beginning with `##` are parsed by name; bullet-list items under each section are
counted. Free-form prose between sections is preserved.
-->

# Session Trace — 2026-09-19

## Task

Refresh MCP and skill governance; add offline compatibility checks and optional lifecycle hooks

## Plan

<!-- 2-5 bullets: what the agent intends to do, in order. -->

- Detect Claude project MCP configuration and fail readiness on unreadable configurations.
- Unify project skill discovery and version full-package approvals with explicit legacy migration.
- Add offline native configuration contracts, provenance and doctor freshness findings.
- Generate optional Codex/Claude lifecycle hooks; test preservation, privacy and loop prevention.
- Document adoption and verify the full suite and repository smoke checks.
- Prepare v0.8.0, validate the package and docs, and publish after CI passes.

## Files Inspected

<!-- Bulleted list of files the agent read but did not modify. -->

- AGENTS.md, pyproject.toml, existing adapters, updater, doctor, MCP and skill implementations.
- Existing CLI help, golden outputs, upgrade tests and scaffold fixture factories.
- Official Agent Skills, Codex configuration/hooks, Claude settings/MCP/hooks and OpenCode documentation.

## Files Changed

<!-- Bulleted list of files the agent wrote to. Include intent in one line each. -->

- src/coding_scaffold/mcp.py and eval_harness.py: detect .mcp.json and reject malformed candidate configuration.
- src/coding_scaffold/skills.py and skill_metadata.py: native locations, required scalar frontmatter, complete-package checksums and migration handling.
- src/coding_scaffold/compatibility.py: offline field checks, source/review metadata and freshness warnings.
- src/coding_scaffold/hooks.py: optional native configuration merging and bounded local lifecycle handler.
- src/coding_scaffold/adapters.py, doctor.py, cli.py and cli_help.py: expose and integrate the new behavior.
- src/coding_scaffold/templates/writers/scaffold.gitignore: ignore local aggregate hook reports.
- tests/test_native_skills.py, test_compatibility.py, test_hooks.py and fixtures: regression, contract, migration and offline execution coverage.
- CHANGELOG.md and wiki Security, Skills and Agents, Tool Adapters, Upgrading: describe usage and limitations.
- .gitignore: include this review trace and exclude generated local graphify output.
- pyproject.toml, uv.lock and CHANGELOG.md: promote the accumulated changes to v0.8.0.

## Commands Run

<!-- Exact commands, one per bullet. Include exit codes if non-zero. -->

- coding-scaffold session init --target . --task "Refresh MCP and skill governance; add offline compatibility checks and optional lifecycle hooks"
- UV_CACHE_DIR=/private/tmp/coding-scaffold-uv-cache uv run --offline ruff check
- UV_CACHE_DIR=/private/tmp/coding-scaffold-uv-cache uv run --offline pytest -q
- UV_CACHE_DIR=/private/tmp/coding-scaffold-uv-cache uv run --offline coding-scaffold context lint --target .
- UV_CACHE_DIR=/private/tmp/coding-scaffold-uv-cache uv run --offline coding-scaffold eval run --target .
- UV_CACHE_DIR=/private/tmp/coding-scaffold-uv-cache uv run --offline coding-scaffold tools compatibility --target .
- git diff --check
- Intermediate targeted runs caught expected golden-path additions, an unused test import and a fixture using manual mode; each was corrected.
- Release validation: `uv lock`, `uv sync --locked --extra dev`, `uv run --offline --locked ruff check`, `uv run --offline --locked pytest -q` and the context/eval/compatibility smoke commands above.
- `uv build --offline --out-dir /private/tmp/coding-scaffold-v0.8.0-dist` and `npm run build` from docs/.

## Test Result

<!-- Summarize. Examples:
- Passed: 167
- Failed: 0
- Skipped: 1
-->

- Passed: 734 tests (66 added); failed: 0; skipped: 0. Release validation completed in 2.98 seconds.
- Ruff and context lint passed; readiness passed 9/9 enabled checks.
- Compatibility: zero errors; one missing-provenance warning in this repository, which has not adopted a generated compatibility manifest.
- Wheel and source distribution built successfully. Documentation built successfully with a non-fatal local Rspack cache-write warning.
- Installed the built wheel into an isolated Python 3.14 environment; verified version 0.8.0, new module imports, native hook generation, native skill creation and compatibility checks.

## Risks

<!-- Anything the change touches that a reviewer should look at carefully. -->

- Required frontmatter is checked with a documented scalar subset, not a general YAML parser.
- Checks cover reviewed native fields and dated documentation snapshots; installed tool versions and live model availability are not probed.
- Lifecycle hooks check scaffold metadata, not project test results or tool permissions. Native hook execution/trust was not exercised in a live agent session.
- Whole-package checksums are unsigned local drift markers; legacy approvals require review and reapproval.
- No new dependencies, runtime network/model calls or telemetry. Local hook reports contain counts and a timestamp, not transcripts.

## Follow-up Recommendations

<!-- Things deliberately not done in this session. -->

- Review native hooks before enabling them in a target project; keep the CLI on the agent's PATH.
- Review upstream contracts and update fixtures and provenance together when the review window expires.
- Jev remains outside this implementation scope.

## Reusable Knowledge Discovered

<!-- Knowledge nudge: at handoff, ask the active coding agent to use its configured model to spot
durable lessons worth remembering. Capture only reviewable candidates here: project facts, team
preferences, decisions, failed attempts, useful commands, gotchas, or reusable prompts. Do not paste
raw chat transcripts, secrets, personal data, or transient conversation. Once promoted, link the
promoted file from the relevant bullet. -->

- Claude project MCP definitions use root .mcp.json with mcpServers, not settings.json's legacy mcp mapping.
- Native Agent Skills do not require a scaffold manifest. Project-local aliases must be deduplicated without reading external skill roots.
- Approving only SKILL.md and manifest.json misses executable helper changes; hash complete package paths, contents and executable bits.
- Hooks need an explicit stop-loop guard and must not confuse metadata readiness with successful project tests.
2 changes: 1 addition & 1 deletion .github/PULL_REQUEST_TEMPLATE/agentic-change.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ leaving it blank.
## Agentic coding disclosure

- **Agent / tool used:** <!-- e.g. Claude Code, Codex, OpenCode, Cursor, manual + Copilot completions -->
- **Model / provider:** <!-- e.g. anthropic/claude-opus-4-7, openai/gpt-5, local: qwen2.5-coder:7b -->
- **Model / provider:** <!-- e.g. anthropic/claude-sonnet-5, openai/gpt-5.6, local: qwen3-coder:30b -->
- **Human operator:** <!-- @your-handle -->
- **Task:** <!-- one-line description of what the change is supposed to do -->

Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ jobs:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.11", "3.12", "3.13"]
python-version: ["3.11", "3.12", "3.13", "3.14"]
steps:
- uses: actions/checkout@v5
- uses: astral-sh/setup-uv@v5
Expand Down
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
!.coding-scaffold/sessions/
.coding-scaffold/sessions/*
!.coding-scaffold/sessions/.gitkeep
!.coding-scaffold/sessions/2026-09-19-agentic-change.md

.claude/settings.local.json
.claude/worktrees/
Expand All @@ -19,6 +20,9 @@ __pycache__/
*.egg-info/
.DS_Store

# Generated local code graph, including machine-specific paths and caches.
/graphify-out/

# rspress docs
node_modules
dist/
Expand Down
68 changes: 68 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,74 @@ aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [0.8.0] — 2026-09-19

### Added

- Offline `tools compatibility` checks for reviewed native configuration fields,
hook structures, skill frontmatter and review freshness; `--strict` also fails
on warnings. Generated compatibility manifests include upstream source URLs,
dated review snapshots and model catalog provenance. `doctor` surfaces findings.
- Opt-in `tools hooks --tool codex|claude-code` generates native `SessionStart`
and `Stop` handlers, preserving existing settings and hooks. The handler runs
local metadata checks and writes aggregate results; it runs no project commands,
makes no network/model calls and stores no transcripts. Stop continuation is
limited to one attempt. Setup/update do not enable hooks automatically.
- Native skill locations for `skills new/approve/export --location` and linting
under `.agents/skills`, `.claude/skills` and `.opencode/skills`. Native manifests
and scaffold-specific headings are optional.

### Fixed

- Claude project `.mcp.json` servers are now scanned; malformed MCP candidate
configuration fails readiness rather than silently passing an empty-server check.
- Skill approvals now cover the full package, including helper scripts, supporting
files, paths and executable bits. Legacy checksums emit a review/migration warning.
Package links and external directory aliases are rejected before approval/export.
- New skill packages include required descriptions. Generated Codex descriptions
are YAML-quoted. Offline native contract fixtures cover adapter/hook output.

- **Claude Code `settings.json` now uses valid permission syntax.** The generated
`"defaultMode": "ask"` was not a Claude Code permission mode, and the deny list
used bare paths (`"**/.env"`), which are not permission rules — so the credential
deny list had no effect. The adapter now writes `"defaultMode": "default"` and
`Read(...)` deny rules (`Read(**/.env)`, `Read(./.coding-scaffold/.env.local)`, …).
The deprecated `includeCoAuthoredBy: false` is replaced by
`"attribution": {"commit": "", "pr": ""}`. Run `coding-scaffold setup update`.
- **Codex `config.toml` now uses current keys.** `approval_mode = "suggest"` came
from the retired TypeScript Codex CLI and is not a valid top-level key today; the
adapter now writes `approval_policy = "on-request"` and
`sandbox_mode = "workspace-write"`. Codex only loads a project-level
`.codex/config.toml` after you trust the project.
- **Codex skills moved to `.agents/skills/<name>/SKILL.md`** with Agent Skills
frontmatter (`name`, `description`). Codex does not discover flat files under
`.codex/skills/`. See
[Upgrading](docs/docs/wiki/Upgrading.md#codex-skills-moved-in-080) for cleanup of
the old files.
- **`open-multi-agent` add-on installs `@open-multi-agent/core`.** The previous
`@jackchen_me/open-multi-agent` package is deprecated on npm; the install plan,
detection path, guide, and TypeScript example now use the new name.
- **Model catalog no longer recommends non-existent Ollama tags.**
`deepseek-coder-v2:16b-lite-instruct` and `qwen/qwen3-coder-40b` do not exist in
the Ollama registry.

### Changed

- **Local model catalog refreshed** to current Ollama tags: `qwen3.5:9b`,
`gpt-oss:20b` (routine) and `devstral-small-2:24b`, `qwen3-coder:30b`,
`qwen3.6:35b-a3b-coding`, `qwen3-coder-next` (heavy-lift). Machines with 8GB RAM
still get no local candidate. Existing `routing.json` files keep their old values
until you re-run `setup run`.
- **Cloud model defaults pinned to current ids** (models.dev naming):
`anthropic/claude-sonnet-5` / `anthropic/claude-haiku-4-5`, `openai/gpt-5.6` /
`openai/gpt-5.4-mini`, `google/gemini-3.1-pro-preview` / `google/gemini-flash-latest`.
- **Claude Code installs via the official native installer**
(`curl -fsSL https://claude.ai/install.sh | bash`) instead of npm, matching the
upstream recommendation. Nothing is installed without consent, as before.
- **Python 3.14 added** to the CI matrix and classifiers.
- **RouteLLM documented as a legacy backend** — upstream has had no commits since
August 2024. The backend still works; the README now says so.

### Deprecated

- **All 14 hidden flat command aliases** (`init`, `wizard`, `update`, `setup-tool`,
Expand Down
12 changes: 7 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -184,8 +184,8 @@ cd ~/dev/my-project
```

Setup can run before any model is configured. It validates the selected coding tool and, when
stdin is interactive, asks before installing a missing tool. OpenCode and Hermes use their official
install scripts; Claude Code, Codex, OpenClaude, and Pi use npm packages. It can also configure
stdin is interactive, asks before installing a missing tool. OpenCode, Hermes, and Claude Code use
their official install scripts; Codex, OpenClaude, and Pi use npm packages. It can also configure
the knowledge backend and optional shared Git remote during setup. Nothing is installed silently.

If you already have `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, Azure variables, `GITHUB_TOKEN`, or a
Expand Down Expand Up @@ -637,7 +637,9 @@ combine it with reviewed credentials, CI checks, identity policy, and network co
## Advanced Options

RouteLLM can provide one OpenAI-compatible endpoint that routes actual requests between a
weak/routine model and a strong/heavy-lift model:
weak/routine model and a strong/heavy-lift model. Note that upstream RouteLLM has had no commits
since August 2024; treat this backend as legacy and evaluate a maintained gateway (for example
LiteLLM's auto-router) before depending on it:

```bash
coding-scaffold setup addon --target ~/dev/my-project --addon routellm
Expand Down Expand Up @@ -701,7 +703,7 @@ Optional commands can also generate:

- `opencode.json`, `.opencode/agents/`, and `.opencode/commands/`.
- `CLAUDE.md`, `.claude/settings.json`, `.claude/commands/`, and `.claude/agents/`.
- `AGENTS.md`, `.codex/config.toml`, and `.codex/skills/`.
- `AGENTS.md`, `.codex/config.toml`, and `.agents/skills/`.
- `.coding-scaffold/team/sources/<kind>/<slug>/`: third-party manifest content imported by
`team sync` (cloned repos keep `.git` inside an `_repo/` subdirectory for fast-forward pulls).
- `.coding-scaffold/ROUTELLM.md` and `routellm.config.yaml`.
Expand Down Expand Up @@ -732,7 +734,7 @@ showing every command. The most common commands are:
## Design Goals

- Cross-platform Linux and WSL behavior.
- Tested Python 3.11 through 3.13, with WSL detection guarded against missing or restricted
- Tested Python 3.11 through 3.14, with WSL detection guarded against missing or restricted
`/proc/version`.
- No secret collection; the scaffold only records whether credentials appear available.
- Local-first routing with explicit cloud escalation.
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/wiki/Review-Backlog.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ linkable — see the cross-references for where the work landed.
- **P1-03 Add A Native Claude Code Adapter** — `coding-scaffold tools adapt --tool claude-code`
generates `CLAUDE.md`, `.claude/settings.json`, slash commands, and the reviewer subagent.
- **P1-04 Add A Native Codex Adapter** — `coding-scaffold tools adapt --tool codex` generates
`AGENTS.md`, `.codex/config.toml`, and `.codex/skills/`.
`AGENTS.md`, `.codex/config.toml`, and `.agents/skills/` (moved from `.codex/skills/` in 0.8.0).
- **P1-05 Add A Compatibility Matrix** — [Tool Adapters / Compatibility Matrix](Tool-Adapters.md#compatibility-matrix)
with 11 capabilities × 6 tools and support-depth labels.
- **P2-01 Make The Knowledge Lifecycle Explicit** — raw/wiki/decisions/sessions structure plus
Expand Down
16 changes: 15 additions & 1 deletion docs/docs/wiki/Security.md
Original file line number Diff line number Diff line change
Expand Up @@ -161,6 +161,11 @@ coding-scaffold mcp diff # report changes since the last snapshot
sudo, bash -c), broad filesystem access (root or home), unapproved servers (when the policy
has a non-empty approved list), denied servers (as errors), and review-required capabilities.

The scanner includes Claude Code's project `.mcp.json` / `mcpServers` format,
alongside the existing OpenCode, Claude settings and Codex TOML locations. It does
not load user-global MCP configuration. Malformed candidate configuration is an
error and fails the readiness check instead of being treated as an empty server list.

`mcp snapshot` + `mcp diff` together let you commit a known-good state and detect drift
in CI. `mcp diff` exits non-zero when anything changed since the snapshot, so it can gate
merges that quietly added a server.
Expand All @@ -175,7 +180,7 @@ manifest.json machine-readable metadata (owner, version, risk_level, capabiliti
scripts/ optional helpers
tests/ optional verification scripts
README.md usage and examples
CHECKSUM sha256(SKILL.md || manifest.json) frozen at approval
CHECKSUM v2 digest of package paths, contents and executable bits
```

`coding-scaffold skills lint` checks every skill for:
Expand All @@ -192,6 +197,15 @@ CHECKSUM sha256(SKILL.md || manifest.json) frozen at approval

`skills export <name>` produces a sharable `tar.gz` for inter-team reuse.

Native project skills under `.agents/skills`, `.claude/skills` and `.opencode/skills`
are scanned too, with required Agent Skills frontmatter. Native manifests and the
scaffold's section conventions are optional. Use `--location agents`, `claude` or
`opencode` for creation, approval and export in those folders. Package links are
rejected so approval cannot silently omit linked executable content. Legacy
two-file checksums are still recognized and reported as needing review; they are
never silently upgraded. A checksum is not a signature and cannot defend against
someone changing both the package and the checksum.

## What this scaffold does not promise

- It does not sandbox agent execution.
Expand Down
34 changes: 33 additions & 1 deletion docs/docs/wiki/Skills-and-Agents.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,39 @@ This creates:

## What A Good Skill Contains

For a native Agent Skills package, use the plural `skills` commands:

```bash
coding-scaffold skills new release-review --location agents --owner @platform
coding-scaffold skills lint --target .
coding-scaffold skills approve release-review --location agents
coding-scaffold skills export release-review --location agents --output release-review.tar.gz
```

Locations are `scaffold` (the existing default, `.coding-scaffold/skills`), `agents`
(`.agents/skills`), `claude` (`.claude/skills`) and `opencode` (`.opencode/skills`).
`skills lint` inspects all four project-local folders, without reading user-global
skills. Native findings include their relative folder path, so duplicate names
remain distinguishable. In-project directory aliases are scanned once.

Generated packages include `name` and `description` frontmatter. The offline
validator accepts plain/quoted strings and indented folded/literal blocks for
these fields; it does not implement a general YAML parser. Names must match their
folder and use lowercase letters/digits separated by hyphens. Native packages do
not require the scaffold-specific manifest or section headings. If a native
package includes a manifest, it is validated. All skills are checked for broad
triggers and hidden instructions.

New approvals cover the complete package, including file paths, contents,
executable bits and supporting instructions. Old approvals produce a migration
warning until reviewed and approved again. External directory links and links or
special files within a package are rejected; copy their contents into regular
project files before approval or export. A checksum is a local drift marker, not
a signature or execution permission. See [Upgrading](Upgrading.md#skill-approval-migration).

The singular `skill` command above retains its legacy Markdown/slash-command
behavior; it does not create a native Agent Skills package.

A good skill is short and procedural:

- when to use it
Expand Down Expand Up @@ -53,4 +86,3 @@ Skills should be reviewed when they:
- encode project-specific architecture rules

The best skills are not clever prompts. They are reliable engineering habits.

Loading
Loading