Skip to content

Commit 050fd62

Browse files
JRS1986JRS1986
authored
Merge pull request #52 from JRS1986/integration/pilot-enablement
Pilot enablement: matrix, threat model, personas, metrics, CHANGELOG
2 parents 6ee3036 + 3e0060a commit 050fd62

5 files changed

Lines changed: 315 additions & 8 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Changelog
2+
3+
All notable changes to CodingScaffold are documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
6+
aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [0.1.0] — 2026-05-18
9+
10+
First tagged release. The scaffold is positioned for a controlled team pilot, not yet for
11+
enterprise-wide governance. See [Team-Rollout / Persona Paths](docs/wiki/Team-Rollout.md#persona-paths)
12+
for the supported entry points.
13+
14+
### Added — core scaffold
15+
16+
- Guided setup (`setup run`) with hardware probe, provider detection, and deterministic
17+
model-selection guidance via `tools select-model`.
18+
- Tool adapters for OpenCode (deep), Claude Code (native config), Codex (native config),
19+
OpenClaude / Hermes / Pi (guidance). Full capability matrix in
20+
[docs/wiki/Tool-Adapters.md](docs/wiki/Tool-Adapters.md#compatibility-matrix).
21+
- Optional add-ons: `llmfit`, `routellm`, `open-multi-agent`, `obsidian`,
22+
`caveman-compression`. Each is installed only on explicit `setup addon` invocation.
23+
- Policy packs (`policy --scope team|company`) that generate reviewable defaults for sharing,
24+
permissions, MCP servers, and provider allow/deny lists.
25+
- Credential templates (`credentials --format env|json`) that never write secret values.
26+
- Team-onboarding manifest workflow: `team init`, `team connect`, `team sync`, `team doctor`.
27+
Imports land under `.coding-scaffold/team/sources/` and never overwrite a user's curated
28+
`.coding-scaffold/knowledge/` tree.
29+
- Context compression (`context compress`) with built-in and optional Caveman engines, plus
30+
budget inspection (`context budget`).
31+
- Knowledge layers (raw, wiki, skills, agents, sharing) with status checks for `owner`,
32+
`last_reviewed`, maturity, and `source_refs`.
33+
- Safe regeneration via `setup update`: drift in generated content is staged as `.new` next to
34+
user-edited files; the version file only advances for files actually written to destination.
35+
36+
### Added — operations
37+
38+
- GitHub Actions CI: `ruff` + `pytest` on push to `main` and on every PR.
39+
- Reproducible installs via `uv` with a committed `uv.lock`. Classic `pip install -e ".[dev]"`
40+
remains supported.
41+
- `coding-scaffold setup tool` validates and (with consent) installs OpenCode, Claude Code,
42+
Codex, OpenClaude, Hermes, or Pi. Install scripts run with a 300-second timeout and captured
43+
output in non-interactive mode.
44+
45+
### Security posture
46+
47+
- Azure endpoint and deployment values are redacted from serialized config (`providers.json`,
48+
adapter JSON) because the subdomain typically encodes tenant identity. Real values live only
49+
in `.env.local`.
50+
- Team-manifest imports are confined to `.coding-scaffold/team/sources/<kind>/<slug>/`. Local
51+
paths and `file://` remotes require `--allow-local`. Cloned repos retain `.git` inside a
52+
hidden `_repo` subdirectory so subsequent syncs use `git pull --ff-only`.
53+
- Local model runtimes are probed for endpoint reachability before being marked available;
54+
having the CLI on `PATH` is no longer sufficient.
55+
- Policy `_merge_opencode_config` deep-merges `mcp.<server>` and `permission.<scope>` and stages
56+
the result as `opencode.json.new` when an existing `opencode.json` is present.
57+
- Context compression no longer strips articles (`the | a | an`) from prose, which previously
58+
corrupted identifiers inside inline code spans and link targets.
59+
- The threat model is documented in [docs/wiki/Security.md](docs/wiki/Security.md#threat-model).
60+
61+
### Known limitations
62+
63+
- The scaffold is reviewable guidance, not a security boundary. Enforcement belongs to the
64+
underlying coding tool, identity layer, network controls, repository protection rules, and CI.
65+
- Runtime model routing is only available for OpenCode (via RouteLLM). Other tools rely on
66+
their own provider configuration plus `tools select-model` recommendations.
67+
- The `setup update` 3-way merge currently has one deferred test scenario; see the open
68+
refactor backlog ([#1](https://github.com/JRS1986/CodingScaffold/issues/1),
69+
[#2](https://github.com/JRS1986/CodingScaffold/issues/2),
70+
[#7](https://github.com/JRS1986/CodingScaffold/issues/7),
71+
[#8](https://github.com/JRS1986/CodingScaffold/issues/8)) for the longer-running work.
72+
73+
### Platforms
74+
75+
- macOS, Linux, and WSL on Python 3.11, 3.12, and 3.13. Earlier Python versions are not
76+
supported. Windows native (outside WSL) works for documentation generation but not for tool
77+
installation — use WSL for the full flow.
78+
79+
[0.1.0]: https://github.com/JRS1986/CodingScaffold/releases/tag/v0.1.0

‎README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,16 @@
11
# CodingScaffold
22

3+
[![CI](https://github.com/JRS1986/CodingScaffold/actions/workflows/ci.yml/badge.svg)](https://github.com/JRS1986/CodingScaffold/actions/workflows/ci.yml)
4+
[![Release](https://img.shields.io/github/v/release/JRS1986/CodingScaffold?sort=semver)](https://github.com/JRS1986/CodingScaffold/releases)
5+
36
Local-first onboarding, configuration, and governance scaffolding for AI-assisted software
47
development teams.
58

9+
> Looking for a specific entry point? See the [persona paths](docs/wiki/Team-Rollout.md#persona-paths)
10+
> (beginner / control-and-reproducibility / security review / team lead). For the threat model
11+
> and what the scaffold deliberately does not enforce, read [Security](docs/wiki/Security.md#threat-model).
12+
> Release notes are in [CHANGELOG.md](CHANGELOG.md).
13+
614
CodingScaffold prepares an existing project for AI-assisted development without tying the team to
715
one model, one provider, or one coding agent. It creates project-local guidance for hardware fit,
816
provider credentials, model selection, coding-tool adapters, skills, agent orchestration, and shared

‎docs/wiki/Security.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,3 +29,102 @@ in the underlying tool, identity layer, network, repository protections, and CI.
2929
Raw notes should stay narrow and reviewable. Curated wiki pages should include owner,
3030
`last_reviewed`, maturity, and `source_refs` so stale or unsourced guidance does not quietly become
3131
agent default behavior.
32+
33+
## Threat Model
34+
35+
CodingScaffold is a bootstrap layer. Security depends on the underlying coding tool, the model
36+
provider, the host OS, and team review discipline. Treat the items below as boundaries the scaffold
37+
**does not** cross, with the mitigation the scaffold provides.
38+
39+
### Install scripts
40+
41+
`coding-scaffold setup tool` and `setup addon` can invoke third-party install commands
42+
(`bash -lc "curl ... | bash"` for OpenCode and Hermes; `npm install -g` for Claude Code, Codex,
43+
OpenClaude, Pi). When stdin is interactive, the scaffold prompts before installing. In
44+
`--non-interactive` mode, installs run unattended with a 300-second timeout and captured output.
45+
46+
- **Risk:** the install URL is whatever the upstream project publishes; a compromised CDN affects
47+
every user.
48+
- **Mitigation:** review the install URL each time the scaffold logs one; pin to a tool version
49+
when your environment supports it; prefer your distribution's package manager when available.
50+
51+
### MCP servers
52+
53+
MCP (Model Context Protocol) servers are code-execution and data-access surfaces. A configured
54+
server can read files, run commands, and call out to external APIs on the agent's behalf.
55+
56+
- **Risk:** an MCP server installed by a teammate may exfiltrate repository contents or run
57+
arbitrary commands during an agent session.
58+
- **Mitigation:** the OpenCode policy pack supports a disable list; review every entry under
59+
`mcp.<server>` in `opencode.json` before merging. Treat team-shared MCP configurations the same
60+
way you'd treat new CI plugins — by code review, not by trust.
61+
62+
### Local model runtimes
63+
64+
Ollama, LM Studio, and llama-server expose OpenAI-compatible endpoints on `127.0.0.1`. The
65+
scaffold probes the endpoint before claiming a runtime is available.
66+
67+
- **Risk:** any process on the same host can call the local endpoint. A malicious local process
68+
could query the model with arbitrary prompts using your loaded weights.
69+
- **Mitigation:** treat local-model endpoints as un-authenticated. Don't bind them to non-loopback
70+
interfaces. Local models are good for code that should not leave the machine; they are not a
71+
multi-tenant access control.
72+
73+
### Cloud providers
74+
75+
The scaffold generates provider records (`providers.json`) and adapter configs that name providers
76+
by env var. API keys never enter generated files. Azure endpoint and deployment values are
77+
redacted from serialized config because the subdomain typically encodes tenant identity.
78+
79+
- **Risk:** the act of using a cloud model sends prompt + context to that provider. Review the
80+
provider's data-retention and training-data policies before allowing it in a project.
81+
- **Mitigation:** `policy --scope company` lets you set an explicit `enabled_providers` /
82+
`disabled_providers` list. Keep secrets in the tool's native auth flow when possible
83+
(GitHub Copilot sign-in, Anthropic OAuth, Azure managed identity).
84+
85+
### Generated policy
86+
87+
Policy packs are guardrail guidance, not enforcement. The underlying tool reads them as
88+
configuration; nothing prevents the user from running the tool with a different config.
89+
90+
- **Risk:** a developer can bypass `share: disabled` or `permission.bash: ask` by editing
91+
`opencode.json` locally.
92+
- **Mitigation:** back local policy with company controls — identity policy on the provider,
93+
network egress rules, secret scanning, repository protection rules, and CI checks. The scaffold
94+
surfaces what *should* be configured; only the platform can enforce it.
95+
96+
### Team manifest content
97+
98+
`team connect` and `team sync` pull markdown content from a remote manifest. Imports land under
99+
`.coding-scaffold/team/sources/` (never in the user's curated `knowledge/`). Local-path and
100+
`file://` remotes require `--allow-local`.
101+
102+
- **Risk:** a teammate's manifest can ship prompt-injection content disguised as a knowledge note,
103+
steering future agent sessions.
104+
- **Mitigation:** team imports are third-party input. Review them before linking from your own
105+
curated knowledge tree. Treat the diff of `team/sources/` like a pull request — because that's
106+
what it is.
107+
108+
### Audit expectations
109+
110+
The scaffold is reviewable by design — generated files live in the repo and change via commits.
111+
Auditors should expect:
112+
113+
- `git log` shows every change to generated config, policy, knowledge, and skills.
114+
- `.env.local`, `credentials.local.json`, and similar files are git-ignored by the generated
115+
`.gitignore`.
116+
- `scaffold-version.json` records the hashes of generated files; drift is detectable via
117+
`coding-scaffold setup update`.
118+
- Sensitive runtime values (API keys, Azure endpoints/deployments) are not present in committed
119+
config; they live in `.env.local` and are resolved at agent-start time.
120+
121+
## What this scaffold does not promise
122+
123+
- It does not sandbox agent execution.
124+
- It does not enforce network egress rules.
125+
- It does not validate model output before it reaches your codebase.
126+
- It does not detect prompt injection in team-imported knowledge.
127+
- It does not encrypt anything in `.coding-scaffold/`; it relies on the host filesystem's controls.
128+
129+
Those responsibilities belong to the coding tool, the OS, the network layer, and the team's CI
130+
and review process.

‎docs/wiki/Team-Rollout.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,3 +65,100 @@ The rollout is working when:
6565
- review findings are caught earlier
6666
- good prompts become skills
6767
- decisions move from chat history into shared knowledge
68+
69+
## Persona Paths
70+
71+
Pick the path that matches the developer you're onboarding. Each path lists who it's for, what
72+
"done" looks like for them, and the smallest command set that gets them there.
73+
74+
### Beginner path — for a junior developer new to agentic coding
75+
76+
**Who:** writes Python or web code, hasn't worked with an autonomous coding agent before. Wants
77+
guardrails, not freedom.
78+
79+
**Success looks like:** after one session, they've inspected the repo with the agent, understood
80+
the test command, and landed one small reviewable change without "magic" edits.
81+
82+
```bash
83+
coding-scaffold setup run --target . --mode beginner
84+
# Review the generated AGENTS.md, .opencode/, and .coding-scaffold/.
85+
opencode # or: claude
86+
# Inside the agent, run /first-session, then /agentic-change on one small issue.
87+
```
88+
89+
The beginner mode includes a first-project guide and conservative defaults
90+
(`permission.edit: ask`, `share: disabled`). Keep policy at `--scope team` until the developer is
91+
comfortable.
92+
93+
### Control / reproducibility path — for the skeptical senior
94+
95+
**Who:** deep expertise in their domain (firmware, embedded, kernel, etc.). Wants traceability,
96+
no surprise edits, and a way to undo anything the agent did.
97+
98+
**Success looks like:** every agent action is visible in `git diff` and reproducible from the
99+
scaffold files alone. They can disable any provider, any MCP server, and audit what the agent saw.
100+
101+
```bash
102+
coding-scaffold setup run --target . --privacy local-only --tool claude-code
103+
coding-scaffold policy --target . --scope team --strict
104+
coding-scaffold credentials --target . --format env
105+
# Review .claude/settings.json (permission.edit: ask, permission.bash: ask).
106+
# Review .coding-scaffold/policy/*.md for the disabled-providers list.
107+
```
108+
109+
Pair with the [Threat Model](Security.md#threat-model) so they see the boundaries explicitly.
110+
111+
### Security review path — for a compliance engineer
112+
113+
**Who:** approves whether the team can use AI coding tools at all. Wants policy defaults,
114+
credential handling, provider constraints, and audit expectations on paper.
115+
116+
**Success looks like:** they can answer "what does this tool generate, what does it not enforce,
117+
and where do real controls live?" using the scaffold's own docs.
118+
119+
```bash
120+
coding-scaffold setup run --target . --tool opencode
121+
coding-scaffold policy --target . --scope company
122+
# Read .coding-scaffold/policy/company.md, opencode.json.new, providers.json.
123+
# Read docs/wiki/Security.md — Threat Model section.
124+
```
125+
126+
The acceptance artifact is the policy diff plus a checklist of which platform controls back it
127+
(identity, network egress, secret scanning, repository protection, CI). The scaffold doesn't
128+
replace any of those; it surfaces what's expected.
129+
130+
### Team-lead path — for a lead establishing shared defaults
131+
132+
**Who:** runs a team where some developers use AI tools privately. Wants AI to become a team
133+
capability with shared prompts, shared knowledge, shared policy.
134+
135+
**Success looks like:** every developer can `team connect` against the same manifest and get the
136+
same generated config, knowledge layer, and policy. New joiners are productive on day one.
137+
138+
```bash
139+
coding-scaffold team init --target . --team platform-api --knowledge-remote <repo-url>
140+
# Customize .coding-scaffold/team-onboarding.json, then commit it.
141+
# Each developer runs:
142+
coding-scaffold team connect --target . --manifest <team-repo>
143+
coding-scaffold team doctor --target .
144+
```
145+
146+
When the manifest changes, every developer runs `team sync` and reviews the diff before merging
147+
imports into their working knowledge.
148+
149+
## Pilot Metrics
150+
151+
These are measurement templates, not features. Track them manually during the pilot. If a number
152+
moves the wrong way, that's the signal to revisit the scaffold or the policy, not the metric.
153+
154+
| Metric | How to measure | Target after 2 weeks |
155+
| --- | --- | --- |
156+
| Time to first safe agentic change | From `setup run` to the first merged PR generated via `/agentic-change`. | < 1 day for the beginner path; < 2 hours for AI power users. |
157+
| Correct-test-command rate | Of agent sessions that ran a test, what fraction ran the project's actual test command (not a guess). | > 80%. Lower means `AGENTS.md` needs more explicit test guidance. |
158+
| CI pass rate after agentic edits | Of PRs containing `/agentic-change` output, what fraction passed CI on first push. | At least matches non-agentic baseline. Below baseline means policy is too permissive or review is too thin. |
159+
| Reusable skills captured | Count of skill entries committed to `.coding-scaffold/knowledge/skills/` during the pilot. | Two or more from each persona path. Zero means workflows aren't being abstracted. |
160+
| Knowledge entries with `last_reviewed` | Of curated wiki pages under `knowledge/wiki/`, what fraction have a `last_reviewed` value within 90 days. | > 90% by end of pilot. Lower means the knowledge layer is decaying. |
161+
| Reverted agentic changes | Count of merged `/agentic-change` PRs reverted within 7 days. | 0-1. Higher signals the scaffold is letting through changes the team can't validate. |
162+
163+
Run a 30-minute retrospective at the end of the pilot. Surface which metric was easiest to gather,
164+
which was hardest, and whether any persona path under- or over-served the developer.

‎docs/wiki/Tool-Adapters.md‎

Lines changed: 32 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -122,14 +122,38 @@ Pi loads `AGENTS.md` project instructions; restart Pi or run `/reload` after cha
122122

123123
## Compatibility Matrix
124124

125-
| Tool | Generated files | Native surface | CodingScaffold stance |
126-
| --- | --- | --- | --- |
127-
| OpenCode | config, agents, commands | providers, local models, permissions, agents | deep/default integration |
128-
| Claude Code | `CLAUDE.md`, settings, commands, reviewer | settings, permissions, MCP, subagents | native config, no runtime control |
129-
| Codex | `AGENTS.md`, config, skills | layered instructions, approvals, local CLI | native guidance, no runtime control |
130-
| OpenClaude | adapter guide | profiles, MCP, slash commands | lightweight guidance |
131-
| Hermes | adapter guide | memory, skills, MCP, backend choices | lightweight guidance |
132-
| Pi | adapter guide | instructions, sessions, extensions | lightweight guidance |
125+
A capability row marked ✓ means CodingScaffold actively generates configuration for that
126+
capability. A row that names a file or flag means the tool's native surface supports it but the
127+
scaffold leaves the configuration to the tool. A dash means the tool either doesn't support the
128+
capability or CodingScaffold has no opinion about it.
129+
130+
| Capability | OpenCode | Claude Code | Codex | OpenClaude | Hermes | Pi |
131+
| --- | --- | --- | --- | --- | --- | --- |
132+
| Install support | ✓ official script | ✓ npm package | ✓ npm package | ✓ npm package | ✓ official script | ✓ npm package |
133+
| Project instructions | ✓ `AGENTS.md` + scaffold guide | ✓ `CLAUDE.md` | ✓ `AGENTS.md` + `.codex/` | ✓ `OPENCLAUDE.md` | ✓ `HERMES.md` | ✓ `PI.md` + `AGENTS.md` |
134+
| Slash commands / skills | ✓ 4 generated | ✓ 2 generated | skills only | doc-only | doc-only | doc-only |
135+
| Agents / subagents | ✓ explorer / implementer / reviewer | ✓ reviewer | — | — | — | — |
136+
| Permissions / approval | ✓ via policy pack | ✓ via `.claude/settings.json` | tool's own approval mode | — | — | — |
137+
| MCP servers | ✓ disable list in policy | settings + docs | — | tool's own | tool's own | — |
138+
| Local model endpoint | ✓ provider detection | tool's own | tool's own | tool's own | tool's own | tool's own |
139+
| Cloud provider allow/deny | ✓ explicit lists in policy | tool's own | tool's own | tool's own | tool's own | tool's own |
140+
| Static per-command profiles | ✓ in commands | partial (settings) | — | — | — | — |
141+
| Runtime routing (RouteLLM) | ✓ via `tools route` | — | — | — | — | — |
142+
| **CodingScaffold support depth** | **deep** | **native config** | **native config** | guidance | guidance | guidance |
143+
144+
Support-depth definitions:
145+
146+
- **deep**: scaffold generates a full set of config + commands + agents and the tool runtime
147+
reads them directly. OpenCode is the only deep target today.
148+
- **native config**: scaffold generates files in the tool's official locations (`CLAUDE.md`,
149+
`AGENTS.md`, `.claude/settings.json`, `.codex/config.toml`) and the tool reads them. Runtime
150+
control stays with the tool.
151+
- **guidance**: scaffold writes a `<TOOL>.md` brief but the tool's own configuration is required
152+
to actually run. Use these when the tool is unfamiliar to the team or moves quickly upstream.
153+
154+
Known gaps: runtime model routing is only available where the tool exposes an OpenAI-compatible
155+
backend swap (today: OpenCode via RouteLLM). For other tools the scaffold relies on the tool's own
156+
provider configuration plus `tools select-model` recommendations.
133157

134158
## Optional Tooling
135159

0 commit comments

Comments
 (0)