Research SPDD + Fowler Fragments + cc-connect; promote 2 rules

.github/copilot-instructions.md

@@ -16,6 +16,7 @@ The universal baseline is in `AGENTS.md`. This file restates the parts that matt
 - Use checklists, tables, and templates.
 - Keep each file under ~200 lines.
 - Markdown only. No HTML except block comments for human-only notes.
+- When a tracked spec, prompt, or design doc governs code, update both in the same change: behavior changes update the spec first then the code; pure refactors change the code first then sync the spec back.
 
 ## Editing rules
 
@@ -24,6 +25,7 @@ The universal baseline is in `AGENTS.md`. This file restates the parts that matt
 - Prefer append-and-refine over replacing whole documents.
 - Do not delete `docs/research-log.md` notes unless the user asks.
 - Do not invent file paths, function names, commands, URLs, or identifiers.
+- Treat "verified" as checked by a deterministic sensor (tests, types, lint, CI gate), not merely read. Prefer adding a sensor over re-reading at scale.
 
 ## Safety
 

AGENTS.md

@@ -28,6 +28,7 @@ Claude Code does not read this file natively; `CLAUDE.md` cross-references it vi
 - One topic per file. Per-path rules go in `.claude/rules/` (Claude) or `.github/instructions/` (Copilot).
 - End any prescriptive instruction file (rules, skills, commands) with a `Boundaries` section that lists what the file does *not* cover and which sibling file does. Forces explicit scope hand-off instead of silent ambiguity.
 - When a file uses YAML frontmatter with a `description:` field, the description must include *trigger phrases* (when to load this) and any competing-tool overrides ("Use this instead of X for Y"), not just a one-line summary.
+- When a tracked spec, prompt, or design doc governs code, keep the two in sync within the same change: for behavior changes, update the spec first then the code; for pure refactors, change the code first then sync the spec back. Never let intent and implementation drift silently.
 
 ## Safety
 
@@ -56,6 +57,7 @@ Before declaring a change done:
 - [ ] No secrets in the diff. `git diff --cached | grep -iE 'api[_-]?key|secret|token|password'` returns nothing.
 - [ ] Each new or edited rule is imperative and verifiable.
 - [ ] Each new source is recorded in `docs/source-repos.md` and `docs/research-log.md`.
+- [ ] "Verified" means checked by a deterministic sensor (tests, type checker, linter, CI gate), not just read. At agent throughput, prefer adding a sensor over re-reading a diff; reserve human review for where judgement genuinely matters.
 
 ## Dev environment tips
 

docs/ai-agent-coding-strategy.md

@@ -72,6 +72,12 @@ See [`docs/knowledge/agentic-pr-review-loop.md`](./knowledge/agentic-pr-review-l
 for the prompt templates, polling schedule, race-condition controls, and
 anti-patterns.
 
+## Practical example: spec/prompt as a tracked artifact
+
+Treating the governing prompt or spec as a version-controlled, reviewed artifact — kept in two-way sync with the code — turns AI assistance from personal speed into governable team capability. Behavior changes update the spec first; pure refactors update the code first then sync the spec back.
+
+See [`docs/knowledge/structured-prompt-driven-development.md`](./knowledge/structured-prompt-driven-development.md) for the seven-part REASONS Canvas, the sync flows, and a fitness assessment.
+
 ## Anti-patterns
 
 - Burying critical constraints inside long prose. Agents will skim past them.

docs/knowledge/README.md

@@ -32,6 +32,12 @@ End each note with a `Boundaries` section listing what the note does *not* cover
   agent separation for PR quality gates, including compact prompts and scheduler
   guardrails.
 - [`azure-genai.md`](./azure-genai.md) — Azure / Azure OpenAI / Foundry / RAG / agents / LLMOps reference notes.
+- [`structured-prompt-driven-development.md`](./structured-prompt-driven-development.md)
+  — REASONS Canvas, the behavior-vs-refactor spec/code sync flows, and a
+  fitness assessment.
+- [`agent-integration-patterns.md`](./agent-integration-patterns.md) —
+  bridge-daemon, capability-interface, plugin self-registration, and preset-manifest
+  patterns for connecting agents and hosts.
 
 ## Planned topics (add when you have material)
 

docs/knowledge/agent-integration-patterns.md

@@ -0,0 +1,63 @@
+# Agent integration patterns
+
+## Purpose
+
+Capture reusable architecture patterns for connecting AI coding agents to each other and to external surfaces, extracted from `chenhg5/cc-connect` (a Go bridge daemon linking local coding agents to chat platforms).
+
+This is a descriptive note. The patterns are language-agnostic even though the source is Go.
+
+## When it applies
+
+Reach for these patterns when building any layer that bridges, multiplexes, or wraps multiple agents or hosts: a connector daemon, an MCP gateway, a multi-agent provider config, or a cross-tool installer.
+
+## Pattern body
+
+### Bridge daemon
+
+A single long-running process connects locally-running agents (Claude Code, Codex, Cursor, Gemini CLI, …) to external surfaces (chat platforms, webhooks) so the agent is drivable remotely with no public IP. The daemon is transport and orchestration only — it carries no instruction logic.
+
+### Capability-interface over identity-switch
+
+Behavior differences between integrations go through capability interfaces, never `if target.Name() == "feishu"`. Adding an integration means implementing an interface, not editing a switch. This keeps the core closed to modification.
+
+### Plugin self-registration with a strict dependency direction
+
+Adapters register themselves at init time (`RegisterAgent()` / `RegisterPlatform()`). The `core/` package must never import `agent/` or `platform/` — dependencies point inward only. The core is the stable nucleus; adapters are the volatile edge.
+
+### Uniform per-host adapter layout
+
+One folder per integration target (`agent/{claudecode,codex,cursor,gemini,…}/`) with the same internal file shape. Predictable layout makes a new adapter a copy-and-fill exercise.
+
+### Versioned, dual-language preset manifest
+
+Catalog-style extension manifests carry `version`, `updated_at`, and per-entry `name` / `display_name` / `description` / localized description / `tags` / `featured`. A provider abstraction nests per-agent-type config (`base_url`, `model`, `models`) so one provider serves heterogeneous agents.
+
+### Secrets and auth posture
+
+Secrets are injected via `${ENV_VAR}` interpolation, never inline. A redaction helper keeps tokens out of logs. Per-project authorization uses an admin allowlist, OS-user isolation for the run-as identity, and role-scoped command denylists and rate limits.
+
+### Session and context lifecycle as config
+
+Idle reset, auto-compression thresholds, and heartbeat intervals are explicit configuration keys, not hardcoded constants — context management is operator-tunable.
+
+## Trade-offs and decision criteria
+
+- Capability interfaces and self-registration add indirection; worth it once there are 3+ integrations, overkill for one.
+- Selective compilation (build tags dropping unused integrations) trims binary size but is language-specific; treat as Go-flavored, not universal.
+- A dual-language manifest is valuable only when the audience is genuinely multilingual.
+
+## Anti-patterns
+
+- Branching on integration identity instead of a capability interface.
+- Letting the core import adapter packages (inverts the dependency arrow; every adapter change risks the core).
+- Inlining credentials instead of env-var interpolation; logging un-redacted tokens.
+- Shipping duplicated `AGENTS.md` and `CLAUDE.md` with no cross-reference — observed in cc-connect and the precise drift hazard the single-source-and-mirror discipline prevents.
+
+## References
+
+- `chenhg5/cc-connect` — <https://github.com/chenhg5/cc-connect>
+- `docs/research-log.md` — dated observations this note was promoted from.
+
+## Boundaries
+
+This note does not cover: the repository's instruction-layering rules (`AGENTS.md`, `CLAUDE.md`), the structured-prompt method (`docs/knowledge/structured-prompt-driven-development.md`), or Azure-specific guidance (`docs/knowledge/azure-genai.md`).

docs/knowledge/structured-prompt-driven-development.md

@@ -0,0 +1,77 @@
+# Structured Prompt-Driven Development (SPDD)
+
+## Purpose
+
+Describe SPDD, a method from Thoughtworks Global IT Services for making LLM-assisted changes governable, reviewable, and reusable by treating the prompt as a first-class delivery artifact kept in version control alongside the code.
+
+This is a descriptive note, not a rule. The promoted imperative ("keep spec and code in two-way sync") lives in `AGENTS.md` house style.
+
+## When it applies
+
+SPDD pays off when change must be governed and carried forward across iterations:
+
+- Scaled or standardized delivery with long-term maintainability.
+- Hard-constraint or compliance systems (financial core, regulated domains).
+- Multi-person delivery where every change must be traceable and reviewable.
+- Cross-cutting refactors where logic must stay synchronized across services.
+
+It does not pay off for firefighting hotfixes, exploratory spikes, one-off scripts, ill-defined domains, or taste-driven creative work.
+
+## The REASONS Canvas
+
+A seven-part structured prompt that moves uncertainty left — from code review to design time.
+
+| Letter | Dimension | Captures |
+|---|---|---|
+| R | Requirements | The problem and the definition of done |
+| E | Entities | Domain entities and their relationships |
+| A | Approach | The strategy for meeting the requirements |
+| S | Structure | Where the change fits; components and dependencies |
+| O | Operations | Concrete, testable implementation steps |
+| N | Norms | Cross-cutting norms (naming, observability, defensive coding) |
+| S | Safeguards | Non-negotiable boundaries (invariants, performance, security) |
+
+R-E-A-S are abstract (intent and design); O is execution; N-S are governance. Because the full specification lives in one artifact, reviewers reason about a single document instead of scattered chat logs and partial diffs.
+
+## Pattern body: the closed loop
+
+The workflow is a closed loop: business input → abstraction → execution → validation → release, with prompt and code evolving together.
+
+Reference tooling (`openspdd`) implements the loop as discrete, versioned CLI steps — analysis, canvas generation, code generation, prompt update, and sync — so artifacts stay reviewable instead of trapped in chat. The structured prompt is never hand-edited; gaps are corrected by instructing the model to update only the affected Canvas sections.
+
+## Spec/code two-way sync
+
+The directional rule that distinguishes SPDD from one-shot spec-driven development:
+
+- **Behavior change** (new requirement, bug fix, logic correction): update the spec first, then regenerate or patch the code from it. "When reality diverges, fix the prompt first — then update the code."
+- **Refactor** (no observable behavior change): change the code first, then sync the spec back so it stays an accurate record of the current code.
+
+Both directions keep intent and implementation from drifting apart. Birgitta Böckeler categorizes this as a *spec-anchored* approach: the spec is maintained, not generated once and discarded.
+
+## Trade-offs and decision criteria
+
+| Benefit | Nature |
+|---|---|
+| Determinism | A precise spec reduces hallucination and creative interpretation |
+| Traceability | Every change traces back to the structured prompt; closes the audit loop |
+| Faster reviews | Code arrives closer to standards; review focuses on logic, not cleanup |
+| Safer evolution | Defined boundaries make targeted change lower-risk |
+
+The upfront cost is real: a design-first mindset shift, senior abstraction skill per feature, and automation tooling to keep prompts consistent. Without automation the method hits a throughput ceiling.
+
+## Anti-patterns
+
+- Treating the spec as write-once scaffolding and letting it rot after first generation.
+- Hand-editing the structured prompt instead of regenerating affected sections.
+- Applying SPDD's governance overhead to throwaway or exploratory work.
+- Skipping the sync-back step after a refactor, so the spec lies about the code.
+
+## References
+
+- Structured-Prompt-Driven Development — <https://martinfowler.com/articles/structured-prompt-driven/>
+- Wei Zhang and Jessie Jie Xia, Thoughtworks, 28 April 2026.
+- `docs/research-log.md` — dated observations this note was promoted from.
+
+## Boundaries
+
+This note does not cover: the repository's instruction-layering rules (`AGENTS.md`, `CLAUDE.md`), the research-handling pipeline (`docs/research-log.md`, `docs/source-repos.md`), or generic agent-integration plumbing (`docs/knowledge/agent-integration-patterns.md`).