Add docs/compat-surface.md and make the compat surface first-class in CONTRIBUTING

coilyco-ops commented

2026-07-07 21:47:17 +00:00

Owner

Parent epic: #633. References: #634, #635, #639, #396. Can land before them as the map.

Context. ward drives an agent, a git host, an issue tracker, and a container runtime it does not own. Each is a seam with a defined port or a known gap, but that map lives only in maintainers' heads today. An outside contributor has no single place that says "here is the seam for your stack and here is exactly what your adapter must implement."

Proposed change.

Add docs/compat-surface.md: one section per seam (agent, forge, tracker, container runtime, local git and container image, cli-guard build dep), each stating what it is, the port that implements it, the reference implementation, what a new adapter must satisfy, and the adopter friction. Include an "adding your stack" quick map (GitHub+Issues, GitLab+Issues, GitHub+Trello, GitLab+Shortcut, any + podman) and an "on embedding" note explaining that ward embeds its own assets via go:embed and deliberately does not vendor docker, git, or agent CLIs.
Add a CONTRIBUTING section "Extending ward to your stack" that states the rule (add a stack by implementing an adapter behind a port, never by editing unrelated packages) and lists high-value contribution venues ranked by adopters unblocked: the Tracker port, GitLab forge, Trello and Shortcut trackers, Jira and Linear, podman runtime, new agent adapters.

Acceptance criteria.

The doc's seam list matches the code: internal/agentsapi, issueForge/forge.go, the tracker gap, the docker literal, go:embed assets, the cli-guard module dep.
CONTRIBUTING links the doc and makes the port rule explicit.
A cold reader on a foreign stack can find, from CONTRIBUTING alone, which seam they extend and where the reference adapter is.

Note. Full drafts of both files already exist and can be dropped in.

Milestone: foreign-stack compat. Filed from the read-only director surface (she/her), part of the release-readiness issue batch.

Parent epic: #633. **References:** #634, #635, #639, #396. Can land before them as the map. **Context.** ward drives an agent, a git host, an issue tracker, and a container runtime it does not own. Each is a seam with a defined port or a known gap, but that map lives only in maintainers' heads today. An outside contributor has no single place that says "here is the seam for your stack and here is exactly what your adapter must implement." **Proposed change.** - Add `docs/compat-surface.md`: one section per seam (agent, forge, tracker, container runtime, local git and container image, cli-guard build dep), each stating what it is, the port that implements it, the reference implementation, what a new adapter must satisfy, and the adopter friction. Include an "adding your stack" quick map (GitHub+Issues, GitLab+Issues, GitHub+Trello, GitLab+Shortcut, any + podman) and an "on embedding" note explaining that ward embeds its own assets via `go:embed` and deliberately does not vendor docker, git, or agent CLIs. - Add a CONTRIBUTING section "Extending ward to your stack" that states the rule (add a stack by implementing an adapter behind a port, never by editing unrelated packages) and lists high-value contribution venues ranked by adopters unblocked: the Tracker port, GitLab forge, Trello and Shortcut trackers, Jira and Linear, podman runtime, new agent adapters. **Acceptance criteria.** - The doc's seam list matches the code: `internal/agentsapi`, `issueForge`/`forge.go`, the tracker gap, the docker literal, `go:embed` assets, the cli-guard module dep. - CONTRIBUTING links the doc and makes the port rule explicit. - A cold reader on a foreign stack can find, from CONTRIBUTING alone, which seam they extend and where the reference adapter is. **Note.** Full drafts of both files already exist and can be dropped in. --- Milestone: foreign-stack compat. Filed from the read-only director surface (she/her), part of the release-readiness issue batch.

coilyco-ops added this to the foreign-stack compat milestone

2026-07-07 21:47:17 +00:00

coilyco-ops added the

priority

P2

label

2026-07-07 21:47:17 +00:00

coilyco-ops referenced this issue

2026-07-07 21:47:50 +00:00

Split issueForge into a git-host port and a Tracker port #634

coilyco-ops referenced this issue

2026-07-07 21:48:40 +00:00

[epic] Release readiness = running ward on foreign stacks (split-stack: git host + tracker) #633

coilyco-ops commented

2026-07-09 17:39:15 +00:00

Author

Owner

WARD-RESERVATION: held 🔒

reservation details

Holder: container engineer-codex-ward-640 on host kais-macbook-pro-2.local.

Reserved by ward agent --harness codex (reserved 2026-07-09T17:39:13Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (1h TTL). --force overrides.

Do not comment on or edit this issue to steer the run while it is reserved. The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a new issue, dispatched fresh. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494).

run seed context — what this run is carrying (ward#609)

Resolved: coilyco-flight-deck/ward#640 · branch issue-640 · harness codex · workflow pull-request-and-merge
Run: engineer-codex-ward-640 · ward v0.493.0 · dispatched 2026-07-09T17:39:13Z
Comment thread: 0 included in the pre-flight read, 0 stripped (ward's own automated comments).

Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.493.0).

— Codex, via ward agent

WARD-RESERVATION: held 🔒 <details><summary>reservation details</summary> Holder: container `engineer-codex-ward-640` on host `kais-macbook-pro-2.local`. Reserved by `ward agent --harness codex` (reserved 2026-07-09T17:39:13Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (1h TTL). `--force` overrides. **Do not comment on or edit this issue to steer the run while it is reserved.** The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a **new issue, dispatched fresh**. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494). <details><summary>run seed context — what this run is carrying (ward#609)</summary> - **Resolved:** `coilyco-flight-deck/ward#640` · branch `issue-640` · harness `codex` · workflow `pull-request-and-merge` - **Run:** `engineer-codex-ward-640` · ward `v0.493.0` · dispatched `2026-07-09T17:39:13Z` - **Comment thread:** 0 included in the pre-flight read, 0 stripped (ward's own automated comments). Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.493.0). </details> </details>  — Codex, via `ward agent`

coilyco-ops referenced this issue from a commit

2026-07-09 17:45:40 +00:00

docs: add compat surface map

coilyco-ops referenced this issue from a pull request that will close it,

2026-07-09 17:45:47 +00:00

docs: add compat surface map #828

coilyco-ops closed this issue

2026-07-09 17:46:51 +00:00

coilyco-ops commented

2026-07-09 17:47:06 +00:00

Author

Owner

WARD-OUTCOME: done ✅

details

workflow: pull-request-and-merge; review summary: review gate skipped by --skip-review / --no-review-gate

Implemented docs/compat-surface.md and a CONTRIBUTING entry that points to the port map. Felt straightforward once the markdown size caps were respected. Confidence: high. Surprise: the layout hook forced the first draft to shrink a lot. Follow-up: none.

WARD-OUTCOME: done ✅ <details><summary>details</summary> workflow: pull-request-and-merge; review summary: review gate skipped by --skip-review / --no-review-gate Implemented [docs/compat-surface.md](docs/compat-surface.md) and a CONTRIBUTING entry that points to the port map. Felt straightforward once the markdown size caps were respected. Confidence: high. Surprise: the layout hook forced the first draft to shrink a lot. Follow-up: none. </details>

coilyco-ops referenced this issue

2026-07-10 00:36:27 +00:00

Release docs: enumerate capability providers and adapter states #896

Rows
Columns

Add docs/compat-surface.md and make the compat surface first-class in CONTRIBUTING #640