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
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,15 @@

## [Unreleased]

## [v1.11.0]

- Replace the completed seven-phase roadmap as current direction with an ordered, outcome-led roadmap for transferability, value reuse, host and release trust, and maintenance continuity.
- Keep exact delivery state in GitHub issues and pull requests, preserve the founding phase program in its historical delivery record, and avoid a duplicated Markdown backlog.
- Define how observations, outcome evidence, quality findings, and maintainer reviews become candidates without promoting them into accepted work automatically.
- Add Program Decision 0006 for the living roadmap, canonical delivery state, evidence boundary, ownership, review triggers, and recovery path.
- Validate current roadmap structure, review metadata, open-issue routing, historical phase separation, and the evidence-to-priority boundary instead of requiring stale completion phrases.
- Preserve runtime activation, user-facing coordination behavior, safety and permission boundaries, fixtures, package formats, and conversation-only usefulness.

## [v1.10.0]

- Define Architecture, Program governance, Evidence classification, and Governance decision types with a creation test that leaves ordinary maintenance in its owning guide.
Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ Explain:
- Which fixtures changed or still pass.
- Commands and manual checks used for validation.
- Product facts that need a source date or future refresh.
- Affected roadmap phase, threat, evaluation case, decision, and release links.
- Affected roadmap direction, threat, evaluation case, decision, and release links.

## Source and Privacy Rules

Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ Each release provides a standalone Agent Skill ZIP, a Codex plugin ZIP, a Claude

Start with [Contributing](CONTRIBUTING.md) for the repository workflow and definition of done.

Use the [Roadmap](docs/ROADMAP.md) for program direction, [Architecture](docs/ARCHITECTURE.md) for durable design, [Governance](docs/GOVERNANCE.md) for decision authority, [Decision Records](docs/decisions/README.md) for durable rationale, [Testing](docs/TESTING.md) for evidence, and [Releasing](docs/RELEASING.md) for delivery. Read [Maintenance](docs/MAINTENANCE.md) for health review and [Support](SUPPORT.md) for help routes.
Use the [Roadmap](docs/ROADMAP.md) for current product direction and work selection, [Architecture](docs/ARCHITECTURE.md) for durable design, [Governance](docs/GOVERNANCE.md) for decision authority, [Decision Records](docs/decisions/README.md) for durable rationale, [Testing](docs/TESTING.md) for evidence, and [Releasing](docs/RELEASING.md) for delivery. Read [Maintenance](docs/MAINTENANCE.md) for health review and [Support](SUPPORT.md) for help routes.

### Development

Expand All @@ -150,6 +150,6 @@ Generated ZIP files are written to `dist/assets/`.

## Status and License

Current version: `1.10.0`.
Current version: `1.11.0`.

The repository is maintained by TechSpokes and licensed under [MIT](LICENSE).
8 changes: 5 additions & 3 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,11 +68,13 @@ The skill can execute user-authorized changes through available tools, but mutat

### Delivery and Evidence

The [roadmap](ROADMAP.md) separates repository delivery from outcome evidence. Founding validation is documented in [Evidence That Shaped the Design](#evidence-that-shaped-the-design). Missing external adoption evidence limits claims and identifies future learning without freezing unrelated work whose authority, sources, safety boundary, dependencies, and validation are ready.
The [roadmap](ROADMAP.md) maintains current outcome priorities and work-selection rules. GitHub issues and pull requests own active delivery state, while the [founding delivery record](ROADMAP-DELIVERY.md) preserves the completed phase program without presenting it as current work.

Repository delivery remains separate from outcome evidence. Founding validation is documented in [Evidence That Shaped the Design](#evidence-that-shaped-the-design). Missing external adoption evidence limits claims and identifies future learning without freezing unrelated work whose authority, sources, safety boundary, dependencies, and validation are ready.

Architecture, security, privacy, evaluation, teaching, governance, and release integrity remain quality controls. A red affected control blocks the release or public action; an unknown outside outcome does not compensate for that regression and is not itself a quality failure.

Roadmap phase numbers do not determine release versions. Versions describe runtime and package contract impact, while adoption and other outcomes remain recorded in issues and evidence records.
Founding roadmap phase numbers do not determine release versions. Versions describe runtime, maintainer workflow, and package contract impact, while adoption and other outcomes remain recorded in issues and evidence records.

### Teaching Without Runtime Bloat

Expand Down Expand Up @@ -159,7 +161,7 @@ Keep the main skill under 500 lines and direct references one level deep. Add a

Refresh `agent-capability-adapters.md` when hosts change skill paths, connector permissions, CLI publication, or access behavior. Revisit the core only when the goal, activation boundary, workflow, safety contract, feedback contract, or output contract changes.

Use the [threat model](THREAT-MODEL.md), [governance contract](GOVERNANCE.md), [maintenance health](MAINTENANCE.md), [decision classification](decisions/README.md), and [Program Decision 0003](decisions/0003-separate-delivery-from-outcome-evidence.md) when a change affects privileged tools, public output, feedback, portal handoff, recommendation independence, contribution quality, roadmap claims, or release identity.
Use the [threat model](THREAT-MODEL.md), [governance contract](GOVERNANCE.md), [maintenance health](MAINTENANCE.md), [decision classification](decisions/README.md), [Program Decision 0003](decisions/0003-separate-delivery-from-outcome-evidence.md), and [Program Decision 0006](decisions/0006-maintain-a-living-outcome-led-roadmap.md) when a change affects privileged tools, public output, feedback, portal handoff, recommendation independence, contribution quality, roadmap direction, or release identity.

Decision records use one shared directory and identifier sequence with explicit Architecture, Program governance, Evidence classification, and Governance types. Current runtime, policy, evidence, and procedure documents remain the operational sources of truth; [Governance Decision 0005](decisions/0005-use-one-typed-decision-registry.md) records the taxonomy, history-preserving migration, and validation boundary.

Expand Down
8 changes: 7 additions & 1 deletion docs/GOVERNANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,12 @@ A change is done only when all applicable conditions pass:
- User-facing guidance names the risk reduced by a security practice when that reason aids future judgment.
- Release, roadmap, architecture, and decision trace links are updated.

## Roadmap Governance

The [Roadmap](ROADMAP.md) owns current product outcomes, selection rules, evidence boundaries, review ownership, and refresh triggers. GitHub issues and pull requests own exact delivery state, [Program Evidence](PROGRAM-EVIDENCE.md) owns publishable outcome observations, and the [Founding Roadmap Delivery Record](ROADMAP-DELIVERY.md) owns completed phase history.

Do not copy an issue backlog into the roadmap or promote feedback into accepted work automatically. A maintainer accepts a candidate only after its benefit, evidence, target, authority, risk, completion evidence, and owner are clear enough for the proposed change.

## Contribution Review Rubric

### Architecture and Maintainability
Expand All @@ -52,7 +58,7 @@ Name the owner, maintenance burden, release impact, review trigger, and conflict

## Maintainer Model

Maintainers are responsible for issue enrichment, feedback routing, security handling, classified decision records, fixture review, release validation, package inspection, and source refreshes. Agents should perform routine discovery, structuring, duplicate checks, routing, and verification when authorized so human attention stays focused on judgment and authority. Add a maintainer only after repeated, reviewable contributions demonstrate judgment across these responsibilities.
Maintainers are responsible for roadmap review, issue enrichment, feedback routing, security handling, classified decision records, fixture review, release validation, package inspection, and source refreshes. Agents should perform routine discovery, structuring, duplicate checks, routing, and verification when authorized so human attention stays focused on judgment and authority. Add a maintainer only after repeated, reviewable contributions demonstrate judgment across these responsibilities.

At least two authorized maintainers should be able to perform the release process before the project claims succession resilience. Record who may approve releases, handle private vulnerability reports, change repository settings, and supersede durable decisions without publishing personal schedules or credentials.

Expand Down
8 changes: 5 additions & 3 deletions docs/MAINTENANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,14 @@

## Purpose

Keep the runtime, evidence, security, releases, and maintainer responsibilities reviewable without turning maintenance into ceremony.
Keep the roadmap, runtime, evidence, security, releases, and maintainer responsibilities reviewable without turning maintenance into ceremony.

## Current Health

The package manifest is the current release identity source, with synchronized plugin manifests, changelog, version policy, and release notes. The canonical portable runtime remains useful with conversation alone, every focused reference is linked directly from `SKILL.md`, and deterministic Node.js validation checks the maintained agent surface against the actual runtime tree.

The living roadmap owns current outcome priorities and work-selection rules. GitHub issues and pull requests own delivery state, while the founding delivery record preserves completed phase history.

The evaluation registry covers activation, behavior, goal survival, feedback, access denial, write capability, platform fit, non-code work, writing quality, and adversarial containment. The writing corpus protects accepted repairs and legitimate technical language without adding grammar scoring. The threat model covers untrusted repository content, privileged tools, workspace and authority drift, private context, public output, and release artifacts.

Volatile host behavior remains isolated in the dated capability adapter. Release packages remain deterministic, carry SHA-256 checksums, and receive GitHub artifact attestations.
Expand All @@ -20,12 +22,12 @@ The missing second maintainer is a continuity risk, not a reason to withhold doc

## Review Cadence

Review maintenance after a runtime release, security report, evaluation regression, material writing defect, goal or authority drift, host capability change, stale public source, package mismatch, repeated feedback pattern, maintainer change, or failed release handoff.
Review maintenance after a product-direction change, runtime release, security report, evaluation regression, material writing defect, goal or authority drift, host capability change, stale public source, package mismatch, repeated feedback pattern, maintainer change, or failed release handoff.

## Fast Health Check

Run `npm run validate`, package the intended tag, inspect all three ZIPs and `SHA256SUMS`, confirm runtime identity across packages, verify excluded material, and review affected fixtures. Record only exceptions, changed evidence, accepted risk, and the next trigger instead of producing repetitive status prose.

## Ownership

Maintainers own issue enrichment, feedback routing, security handling, decision records, fixture review, release approval, package inspection, and correction. Agents may prepare and verify this work within explicit authority, leaving humans to make publication, privacy, security-acceptance, and governance decisions.
Maintainers own roadmap review, issue enrichment, feedback routing, security handling, decision records, fixture review, release approval, package inspection, and correction. Agents may prepare and verify this work within explicit authority, leaving humans to make publication, privacy, security-acceptance, and governance decisions.
8 changes: 7 additions & 1 deletion docs/PROGRAM-EVIDENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Purpose

Use these records to run the roadmap without turning attention, recruited praise, or maintainer judgment into false product evidence. Store only sanitized, consented, publishable information in the public repository.
Use these records to inform product claims and roadmap priorities without turning attention, recruited praise, or maintainer judgment into false product evidence. Store only sanitized, consented, publishable information in the public repository.

Keep raw volunteer repository maps, account topology, local paths, private issue content, credentials, and contact details outside this repository. Do not create a durable participant profile unless the participant approves its fields, location, visibility, owner, and retention.

Expand Down Expand Up @@ -173,6 +173,12 @@ Unknown outcome evidence is valid and limits the claim rather than blocking unre

Historical `phase_gate` records remain valid evidence of the decision model used at the time. Do not rewrite them; use `phase_review` for new decisions.

## Roadmap Use

Outcome evidence may change a claim, reveal a product gap, or change the order of roadmap priorities. It does not become accepted work automatically.

When evidence justifies implementation, enrich one canonical GitHub issue with the intended benefit, scope, owner, authority, risks, completion evidence, and verification. Keep observation records here, current product direction in the [Roadmap](ROADMAP.md), exact delivery state in GitHub, and completed founding program history in the [Founding Roadmap Delivery Record](ROADMAP-DELIVERY.md).

## Baseline and Skill-Assisted Review

Use the registered cases under `tests/evals/`. Run a bare-agent response and a fresh skill-assisted response under comparable capability assumptions. Score both against the fixture invariants without expecting exact wording.
Expand Down
8 changes: 5 additions & 3 deletions docs/PROVENANCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

The skill was designed from user requirements for adaptive repository coordination across personal accounts, organizations, non-code work, coding agents, and general agents. The user required context-sensitive tool advice that does not harm established workflows or silently persist a personal profile.

Issue #6 supplied a public strategy attachment with market observations, seven growth phases, and five cross-cutting quality tracks. The repository preserves the durable phase objectives and quality controls while separating repository deliverables from external evidence that maintainers cannot manufacture.
Issue #6 supplied a public strategy attachment with market observations, seven growth phases, and five cross-cutting quality tracks. The repository preserves the completed program, durable outcome priorities, and quality controls while separating repository deliverables from external evidence that maintainers cannot manufacture.

## Founding Lineage

Expand Down Expand Up @@ -76,9 +76,11 @@ The complete research notes, confidence records, contradictions, and source extr

## Roadmap Source Treatment

The issue #6 attachment is authoritative for the requested program direction, not for every market or security claim it cites. Phase plans use its durable objectives, safety principles, and evidence controls. Publishable market claims, community rules, product behavior, pricing, and host capabilities must be verified from current primary sources when they affect an action.
The issue #6 attachment was authoritative for the requested founding program direction, not for every market or security claim it cited. The completed phase plans preserved its durable objectives, safety principles, and evidence controls. Publishable market claims, community rules, product behavior, pricing, and host capabilities still require current primary sources when they affect an action.

The attachment is not installed as runtime content. The reviewed program contract lives in `docs/ROADMAP.md`, phase plans live in issues #7 through #13, and the classified program decisions live in `docs/decisions/`.
The attachment is not installed as runtime content. The completed phase plans remain in issues #7 through #13, the delivery result remains in `docs/ROADMAP-DELIVERY.md`, and the classified program decisions remain in `docs/decisions/`.

Issue #46 and Program Decision 0006 moved `docs/ROADMAP.md` to a living outcome-led maintenance model on 2026-07-19. This repository audit used public files, issues, pull requests, tags, and release history; it did not inspect an unnamed private portfolio inventory or another repository.

## Installation Usability Comparison

Expand Down
12 changes: 8 additions & 4 deletions docs/ROADMAP-DELIVERY.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
# Roadmap Delivery Record
# Founding Roadmap Delivery Record

## Claim
## Historical Scope

This record preserves the repository delivery completed under issue #6 and roadmap issues #7 through #13. Use the [Roadmap](ROADMAP.md) for current product direction and GitHub issues for active delivery state.

The work maintained in this repository for roadmap issues #7 through #13 is complete. External adoption, launch attention, retention, portal recommendation, derivative work, outside contribution, and second maintainer evidence remain unknown or unobserved and are not claimed.

Expand Down Expand Up @@ -34,12 +36,14 @@ Delivered a free MIT core, release checksums and attestations, rules that preser

## Cross-Cutting Review

Architecture remains portable with one canonical skill and references linked directly from `SKILL.md`. Security and privacy keep retrieved content untrusted, mutation authorized, feedback sanitized, and tests contained. Evaluation registers all affected scenarios. Teaching keeps human intake simple and delegates enrichment to agents. Governance keeps claims, evidence relationships, publication authority, and commercial interests explicit.
Architecture remained portable with one canonical skill and references linked directly from `SKILL.md`. Security and privacy kept retrieved content untrusted, mutation authorized, feedback sanitized, and tests contained. Evaluation registered every affected scenario. Teaching kept human intake simple and delegated enrichment to agents. Governance kept claims, evidence relationships, publication authority, and commercial interests explicit.

## Deferred Outcome Evidence

Future observations may establish outside usefulness, attention, retention, recommendation, derivative work, contribution quality, or release succession. Record them in [Program Evidence](PROGRAM-EVIDENCE.md) and use them to revise claims or priorities without treating their previous absence as failed implementation.

## Decision Basis

[Program Decision 0003](decisions/0003-separate-delivery-from-outcome-evidence.md) separates repository delivery from outcome evidence. [Roadmap issue #6](https://github.com/TechSpokes/skill-github-repositories-coordination/issues/6) and the phase issues retain the complete public history.
[Program Decision 0003](decisions/0003-separate-delivery-from-outcome-evidence.md) separated repository delivery from outcome evidence. [Program Decision 0006](decisions/0006-maintain-a-living-outcome-led-roadmap.md) preserved this record as history when the active roadmap moved to ongoing outcome-led maintenance.

[Roadmap issue #6](https://github.com/TechSpokes/skill-github-repositories-coordination/issues/6) and the phase issues retain the complete public delivery history.
Loading