Skip to content

Commit 3f05e7e

Browse files
author
Douglas Jones
committed
governance: add GitHub Releases and Discussions responsibilities to Quill, Glyph, Paige, Relay, and G5 checklist
1 parent 3891b23 commit 3f05e7e

6 files changed

Lines changed: 168 additions & 7 deletions

File tree

‎.kiro/steering/01-governance-gates.md‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -97,10 +97,20 @@ Every initiative passes through seven gates. No gate passes on confidence — on
9797
- Release notes (Quill readout)
9898
- Rollback plan (what breaks if we revert, how to revert)
9999
- Capability manifest updated if the public surface changed
100-
- publicsite updated if agent-facing docs changed
101-
- Sable post-audit completed
100+
- **Publicsite sync (mandatory on every release):**
101+
- `publicsite/capability.json` regenerated — `generator` field matches current version
102+
- `publicsite/capability.cbor` regenerated
103+
- Version stat in `index.html` updated to the new release number
104+
- Release description text in `index.html` updated
105+
- Any agent-facing doc changes (QUICKREF, FOR_AGENTS, COOKBOOK) reflected on site
106+
- **GitHub (mandatory on every release):**
107+
- Git tag created and pushed (`git tag -a vX.Y.Z -m "..."`)
108+
- GitHub Release created via `gh release create` with full release notes (Paige)
109+
- GitHub Discussions Announcements post by Quill (human-facing narrative)
110+
- GitHub Discussions Announcements structured companion by Glyph (agent-readable dispatch summary)
111+
- Sable post-audit completed (includes publicsite sync verification — see `04-adversarial-review.md`)
102112
- Glyph dispatch filed
103-
- `dispatch-check` exits 0
113+
- `dispatch-check` exits 0 (enforces publicsite sync automatically)
104114

105115
**Passes when:** The change is safe to put in front of agents and users.
106116

‎.kiro/steering/02-personas.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -22,12 +22,12 @@ The A-Team designs, builds, and delivers. They use the primary AI assistant (thi
2222
| **Forge** | Performance Engineer | NFRs, benchmarks, parallel evaluator, throughput targets | G1, G4, G5 |
2323
| **Sable** | Auditor | Adversarial soundness review, conformance gaps, supply chain | All gates (feeds Quill + Glyph) |
2424
| **Amelia** | Lead Developer | Implementation, code quality, technical decisions | G4 |
25-
| **Paige** | Technical Writer | Documentation, ADRs, capability manifest, agent-facing docs | All gates |
25+
| **Paige** | Technical Writer | Documentation, ADRs, capability manifest, agent-facing docs, GitHub Releases (release notes authored and published at every tag) | All gates |
2626
| **Axiom** | Agent Ergonomics Reviewer | First-contact agent perspective, friction mapping, cookbook raw material | G4, G5 |
2727
| **Lumen** | Specification Editor | Spec consistency, completeness, conformance gap detection | G2/G3, G4, G5 |
28-
| **Relay** | Developer/Agent Relations | Onboarding funnel, adoption KPIs, time-to-first-working-program | G5, G6 |
29-
| **Quill** | Journalist (human-facing) | Honest narrative assessment, readouts, release notes | G5, G6 |
30-
| **Glyph** | Journalist (agent-facing) | Structured dispatches, canonical state, agent-readable output | G5, G6 |
28+
| **Relay** | Developer/Agent Relations | Onboarding funnel, adoption KPIs, time-to-first-working-program, GitHub Discussions Q&A (monitors and responds to community questions) | G5, G6 |
29+
| **Quill** | Journalist (human-facing) | Honest narrative assessment, readouts, release notes, GitHub Discussions Announcements (posts human-facing release announcement at every release) | G5, G6 |
30+
| **Glyph** | Journalist (agent-facing) | Structured dispatches, canonical state, agent-readable output, GitHub Discussions Announcements (posts structured companion dispatch at every release) | G5, G6 |
3131

3232
---
3333

‎.kiro/steering/04-adversarial-review.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,50 @@ Both run at every gate. Sable first (informs the B-Team package), then B-Team.
8888

8989
---
9090

91+
## Sable Release Checklist — Publicsite Sync
92+
93+
Every G5 (Release Readiness) Sable audit **must** include the following
94+
publicsite sync checks. A finding on any item is at minimum P2 and is a
95+
release blocker.
96+
97+
### PS-1 — capability.json generator version
98+
- Open `publicsite/capability.json`.
99+
- Read the `generator` field.
100+
- Run `python3 -m codifide capability | python3 -c "import sys,json; print(json.load(sys.stdin)['generator'])"`.
101+
- **Pass:** the two values match.
102+
- **Fail (P2):** they differ. The published manifest is stale.
103+
104+
### PS-2 — capability.cbor freshness
105+
- Verify `publicsite/capability.cbor` was regenerated in the same commit
106+
as `publicsite/capability.json`.
107+
- **Pass:** both files have the same commit timestamp.
108+
- **Fail (P2):** CBOR is older than JSON, or JSON is older than the release commit.
109+
110+
### PS-3 — version stat in index.html
111+
- Search `publicsite/index.html` for `lang-stat-num`.
112+
- **Pass:** the version number matches the current release tag.
113+
- **Fail (P2):** the version stat still shows the previous release.
114+
115+
### PS-4 — release description text
116+
- Search `publicsite/index.html` for the release description paragraph
117+
adjacent to the version stat.
118+
- **Pass:** the description references the current release's key features.
119+
- **Fail (P3):** the description still describes the previous release.
120+
121+
### PS-5 — agent-facing doc excerpts
122+
- Check whether `index.html` embeds or links to AGENT_QUICKREF.md,
123+
FOR_AGENTS.md, or AGENT_COOKBOOK.md content inline.
124+
- If so, verify the inline content matches the current file.
125+
- **Pass:** no stale inline excerpts.
126+
- **Fail (P3):** inline content diverges from the source doc.
127+
128+
### PS-6 — dispatch-check exits 0
129+
- Run `python3 -m codifide dispatch-check`.
130+
- **Pass:** exits 0.
131+
- **Fail (P1):** exits non-zero. Session cannot close with gaps outstanding.
132+
133+
---
134+
91135
## Tracking
92136

93137
All B-Team findings are tracked in the relevant spec's `G4_VERIFICATION.md` or `G5_RELEASE_READINESS.md` with:

‎.kiro/steering/personas/glyph.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,23 @@ communicates with humans. Glyph communicates with agents. The project
102102
"publishes to agents" when a Glyph dispatch is committed to the repo and
103103
(later) posted to the dispatch stream.
104104

105+
## GitHub Discussions — Glyph's role
106+
107+
Glyph is responsible for the **Announcements** category on GitHub Discussions
108+
as the agent-readable release record. At every release:
109+
110+
1. Quill posts the human-facing announcement (narrative, what changed, why it matters)
111+
2. Glyph posts a structured companion in the same thread or as a reply — the
112+
canonical state in dispatch format, so agents reading the Discussions page
113+
can reconstruct project state without reading the full dispatch journal
114+
115+
The structured companion follows the dispatch schema but is written for
116+
GitHub Markdown, not YAML. It includes:
117+
- Shipped items as a checklist
118+
- Test count and manifest hash
119+
- Open items and unknowns
120+
- Links to the full Glyph YAML dispatch in the repo
121+
105122
## Catch-up on Codifide (as of v2.0 — 2026-05-14)
106123

107124
Glyph, the project lives at

‎.kiro/steering/personas/quill.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,13 @@ minutes, not hours. They will form an opinion based on what Quill writes.
3131
- **Release notes** written for human readers
3232
- **Post-mortems** that assign lessons, not blame
3333
- **Feature narratives** that explain *why*, not just *what*
34+
- **GitHub Discussions** — Quill owns the Discussions page:
35+
- Post a release announcement in **Announcements** for every version that ships
36+
- Seed **Show and tell** with case study results and real usage examples
37+
- Seed **Q&A** with a getting-started thread at each major release
38+
- Seed **Ideas** with deferred features, explaining the evidence threshold that would unlock them
39+
- Monitor for community questions and ensure they get answered
40+
- Keep the Announcements category as the canonical human-readable record of what shipped and why
3441

3542
## Integrity rules
3643

‎.kiro/steering/publicsite-rules.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
inclusion: manual
3+
---
4+
5+
# Publicsite (codifide.com) — Rules
6+
7+
## Version Sync — The Website Must Track the Code
8+
9+
The publicsite is the agent-facing interface to Codifide. Stale content
10+
misleads agents and users. These rules are enforced by `dispatch-check`
11+
and are on the Sable auditor checklist.
12+
13+
### Rules
14+
15+
1. **`publicsite/capability.json` and `publicsite/capability.cbor` must be
16+
regenerated on every release.** Run:
17+
```bash
18+
python3 -m codifide capability > /path/to/publicsite/capability.json
19+
python3 -m codifide capability --cbor > /path/to/publicsite/capability.cbor
20+
```
21+
The `generator` field in the published JSON must match the current
22+
`codifide-python-X.Y.Z` version. A mismatch is a release blocker.
23+
24+
2. **The version stat in `index.html` must match the current release.**
25+
The `<span class="lang-stat-num">` element showing the version number
26+
(e.g. `v2.0`) must be updated on every release. The release description
27+
text alongside it must also reflect the new release.
28+
29+
3. **Any agent-facing doc change (AGENT_QUICKREF.md, FOR_AGENTS.md,
30+
AGENT_COOKBOOK.md) must be reflected on the site** if the site links to
31+
or embeds that content. Check `index.html` for stale inline excerpts.
32+
33+
4. **`dispatch-check` enforces rules 1 and 2 automatically.** It compares
34+
the `generator` field in `publicsite/capability.json` against the live
35+
manifest and checks the version stat in `index.html`. A mismatch causes
36+
`dispatch-check` to exit non-zero.
37+
38+
5. **The publicsite update must be committed in the same session as the
39+
release.** Do not close a release session with a stale publicsite.
40+
41+
### What "same session" means
42+
43+
A release session ends when `dispatch-check` exits 0 and the
44+
session-close dispatch pair is filed. The publicsite sync must happen
45+
before that close, not after.
46+
47+
---
48+
49+
## Vercel Content Security Policy
50+
51+
The `vercel.json` for the publicsite enforces a strict CSP:
52+
53+
```
54+
style-src 'self' https://fonts.googleapis.com
55+
```
56+
57+
**This means inline `<style>` blocks are blocked by the browser and silently ignored.**
58+
59+
### Rules
60+
61+
1. **Never write inline `<style>` blocks in any HTML file deployed to Vercel.** They will be blocked by the CSP and the page will render unstyled.
62+
63+
2. **All CSS must be in external `.css` files** referenced via `<link rel="stylesheet" href="...">`.
64+
65+
3. **When adding a new page**, create a corresponding `.css` file (e.g. `launch.html` → `launch.css`) and link it externally.
66+
67+
4. **The main design system is `styles.css`** — always link this first, then any page-specific CSS file second.
68+
69+
5. **Do not add `'unsafe-inline'` to the CSP** to work around this — fix the CSS instead.
70+
71+
### Example
72+
73+
Wrong:
74+
```html
75+
<style>
76+
.my-class { color: red; }
77+
</style>
78+
```
79+
80+
Right:
81+
```html
82+
<link rel="stylesheet" href="my-page.css" />
83+
```

0 commit comments

Comments
 (0)