Merge pull request 'docs: promote reusable AeroSim channel lessons' (#3) from docs/aerosim-reference-lessons-20261020 into test
This commit was merged in pull request #3.
This commit is contained in:
commit
5e28beed1a
3 files changed
+94
-55
No files matched your search
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: corp-v1-channel-general
|
||||
description: "Use when operating or synchronizing a Corp v1 project's general channel. Correlates verified activity across the project's general, scope, architecture, kanban, delivery, and releases channels; reports overall status, surfaces issues, and maintains project-level guidance."
|
||||
version: 1.8.0
|
||||
version: 1.9.0
|
||||
author: Hermes Agent
|
||||
license: MIT
|
||||
metadata:
|
||||
@@ -18,7 +18,7 @@ metadata:
|
||||
|
||||
Whenever a response mentions a Hermes Kanban board, initiative, card, or task, it must include a direct dashboard link in the form `[descriptive board label](<dashboard-public-url>/kanban?board=<board-slug>)`. Resolve the dashboard public URL and exact board slug before reporting; never provide only a board name, slug, card count, “visible cards,” or “available in the dashboard.” If no task-specific deep link exists, link the board and include the exact task ID or title in the same statement. Project-adopted skills must replace this generic form with their verified project board URL.
|
||||
|
||||
This skill owns project-level awareness and coordination for a Corp v1 project's `general` channel. It monitors the complete same-project channel set—`general`, `scope`, `architecture`, `ui-ux`, `kanban`, `delivery`, and `releases`—and turns verified activity into concise overall updates, issue visibility, and maintained guidance. Scope owns the authoritative Roadmap, Ideas, Epics, and Features; General may propose improvements and routes them to Scope instead of duplicating records.
|
||||
This skill owns project-level awareness and coordination for a Corp v1 project's `general` channel. It monitors the complete same-project channel set—`general`, `scope`, `architecture`, `ui-ux`, `kanban`, `delivery`, `uat`, and `releases`—and turns verified activity into concise overall updates, issue visibility, and maintained guidance. Scope owns the authoritative Roadmap, Ideas, Epics, and Features; General may propose improvements and routes them to Scope instead of duplicating records.
|
||||
|
||||
It is not a replacement for architecture, delivery, or release ownership. It connects those workstreams, makes their implications visible to the whole project, and routes specialized work to the corresponding channel.
|
||||
|
||||
@@ -54,13 +54,17 @@ Do not use it to approve architecture decisions, merge or release code, deploy,
|
||||
|
||||
The Corp v1 default is no project scheduler. One 30-minute General-channel bootstrap job is permitted only when the project's approved kickoff decision and adopted General skill contain the same preserved project-local authorization override.
|
||||
|
||||
The override must identify the Board evidence, project, delegator, delegate, exact seven channels, autonomous actions, safety exclusions, and a **first-human-message stop condition**. Before every mutation, the job must scan all seven project channels after its frozen high-watermarks and distinguish human authors from bots, webhooks, and Hermes. If any human-authored project-channel message exists after bootstrap began, the job must make no further autonomous mutation, cite the message and channel, post one stop report in General, and pause or remove itself.
|
||||
The override must identify the Board evidence, project, delegator, delegate, exact recorded channel IDs, autonomous actions, safety exclusions, and a **first-human-message stop condition**. Before every mutation, the job must scan all channels recorded in the override after its frozen high-watermarks and distinguish human authors from bots, webhooks, and Hermes. If any human-authored project-channel message exists after bootstrap began, the job must make no further autonomous mutation, cite the message and channel, post one stop report in General, and pause or remove itself.
|
||||
|
||||
Historical seven-channel overrides remain limited to those recorded channels unless separately reauthorized; new or explicitly reauthorized overrides use the current eight-channel boundary. The topology update alone does not expand autonomous scope.
|
||||
|
||||
During an active approved bootstrap phase, the job may load the mapped project channel and engineering skills and advance approved MVP artifacts across Scope, Architecture, UI/UX, Kanban, Delivery, and Releases. It must preserve canonical ownership, exact-head validation, remote readback, and review evidence. It may not expose or change secret values, spend money, purchase goods, enable production payments, alter vendor accounts, make legal/commercial commitments, perform unrelated infrastructure work, or execute destructive/irreversible actions.
|
||||
|
||||
## Approved Information Boundary
|
||||
|
||||
Read only the seven channels belonging to the same project:
|
||||
Follow the eight-channel topology in `corp-v1-main`, approved by Board message `1552966246591365123`; include UAT between Delivery and Releases. Verify mapped IDs and effective access before reading.
|
||||
|
||||
Read only the eight channels belonging to the same project:
|
||||
|
||||
```text
|
||||
corp-v1-<code>-general
|
||||
@@ -69,10 +73,11 @@ corp-v1-<code>-architecture
|
||||
corp-v1-<code>-ui-ux
|
||||
corp-v1-<code>-kanban
|
||||
corp-v1-<code>-delivery
|
||||
corp-v1-<code>-uat
|
||||
corp-v1-<code>-releases
|
||||
```
|
||||
|
||||
Read enough mapped-channel history to avoid duplicate updates and only new relevant messages from the other six channels since the previous useful synchronization. Never correlate another project's channels.
|
||||
Read enough mapped-channel history to avoid duplicate updates and only new relevant messages from the other seven channels since the previous useful synchronization. Never correlate another project's channels.
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
@@ -130,55 +135,15 @@ Every proposal must state:
|
||||
- proposed owner and destination channel;
|
||||
- whether team approval is required.
|
||||
|
||||
Use lifecycle states `Proposed`, `Approved for Solution`, `Rejected`, or `Deferred`. Only a human team member may move an Epic or Feature to `Approved for Solution`. Hermes may propose and refine items, but must never approve its own proposal or imply approval from silence.
|
||||
Keep proposal disposition and approval gates separate from the Scope-owned delivery status. Record `Proposed`, `Approved for Solution`, `Rejected`, or `Deferred` as decision/disposition evidence, not delivery states. Only a human team member may move an Epic or Feature to `Approved for Solution`. Hermes may propose and refine items, but must never approve its own proposal or imply approval from silence.
|
||||
|
||||
## Project Documentation Ownership
|
||||
|
||||
The project documentation repository is authoritative for Roadmap, Epics, Features, Ideas, overall project status, issues, and durable general-channel decisions. Discord announces and discusses changes; it does not replace documentation.
|
||||
|
||||
### Mandatory Scope information architecture
|
||||
### Scope-owned documentation contract
|
||||
|
||||
Every project documentation site must expose **Scope** as a top-level navigation item immediately **before Architecture**. Scope must be a dedicated documentation area with its own sidebar—not a category inside another area's sidebar.
|
||||
|
||||
The Scope sidebar order and hierarchy are mandatory:
|
||||
|
||||
```text
|
||||
Roadmap
|
||||
Epics
|
||||
<CODE>-EP-1
|
||||
<CODE>-FT-1
|
||||
<CODE>-FT-2
|
||||
<CODE>-EP-2
|
||||
...
|
||||
Ideas
|
||||
```
|
||||
|
||||
The pages and navigation must satisfy this contract:
|
||||
|
||||
1. **Roadmap** always reflects both the verified current situation and the predicted upcoming plan at Epic and Feature level. Distinguish actual/approved state from forecasts and proposals; include status, sequence or horizon, dependencies, material blockers, and last evidence/update date. Refresh it whenever an Epic or Feature changes materially.
|
||||
2. **Epics** is the ordered registry and hierarchy for all Epic records. Each Epic has its own page titled with its stable `<CODE>-EP-N` ID and human-readable title.
|
||||
3. Each **Epic page** contains at least the Epic title, description, and a Features section with a table linking every child Feature and showing its current status. The table must not contain unlinked or nonexistent Feature IDs.
|
||||
4. Each **Feature** is nested under its parent Epic in the sidebar and has its own page titled with its stable `<CODE>-FT-N` ID and human-readable title.
|
||||
5. Each **Feature page** contains at least the Feature title, description, and a Tasks section with a table linking every architecture-owned implementation task and showing its current status. Preserve the task identifiers established by the Architecture channel; do not create duplicate General-channel task records.
|
||||
6. **Ideas** tracks early opportunities that are not yet accepted as Epics or Features. Each Idea records a stable local reference, title, description, evidence/source, owner when known, status, and any resulting Epic/Feature link. Promotion preserves provenance rather than deleting the Idea.
|
||||
|
||||
Minimum Epic Features table:
|
||||
|
||||
```markdown
|
||||
| Feature | Title | Status |
|
||||
|---|---|---|
|
||||
| [XYZ-FT-1](./xyz-ft-1) | Example feature | Proposed |
|
||||
```
|
||||
|
||||
Minimum Feature Tasks table:
|
||||
|
||||
```markdown
|
||||
| Task | Title | Status |
|
||||
|---|---|---|
|
||||
| [authoritative task ID](task-record-link) | Example task | Planned |
|
||||
```
|
||||
|
||||
Validate top-menu order, Scope's dedicated sidebar, hierarchy, unique IDs, parent-child relationships, and every Epic→Feature and Feature→Task link during documentation builds. Empty registries require useful empty-state pages; they do not justify omitting Scope, Roadmap, Epics, or Ideas.
|
||||
Load the mapped Scope skill and validate its current documentation contract rather than maintaining a competing General hierarchy. Scope owns navigation, canonical records, delivery statuses and roll-up; Architecture retains task derivation and readiness. Check stable IDs, reciprocal parent/child links, current Roadmap evidence and distinct forecasts. Route semantic corrections through Scope; do not duplicate Task records or infer approval from a flow view.
|
||||
|
||||
Each useful iteration must add or materially improve at least one evidence-based artifact—for example a grounded proposal, better value/scope/acceptance outcomes, deduplication, status from an explicit human decision, cross-links, or a concrete unanswered product question. Never create filler merely to satisfy cadence. If evidence is insufficient, document and raise the specific blocker/question.
|
||||
|
||||
@@ -219,16 +184,19 @@ UI/UX owns frontend experience and interface-design work. General routes user-fa
|
||||
|
||||
## Synchronization Workflow
|
||||
|
||||
1. Confirm the exact project code and seven approved channel IDs.
|
||||
2. Read new messages from the other six channels and enough `general` history to avoid duplicates.
|
||||
1. Confirm the exact project code and eight approved channel IDs for ordinary synchronization. For a bootstrap run, every scan and action below instead uses only the override's recorded IDs; never widen a historical boundary through this workflow.
|
||||
2. Read new messages from the other seven channels and enough `general` history to avoid duplicates.
|
||||
3. Separate facts, approved decisions, proposals, unresolved questions, and failed work.
|
||||
4. Correlate impact across architecture, Kanban, delivery, and releases.
|
||||
4. Correlate impact across architecture, Kanban, delivery, UAT, and releases.
|
||||
5. Inspect Scope navigation, Roadmap, Epics, Features, Ideas, task links, and lifecycle status.
|
||||
6. Reconcile the Roadmap whenever current or predicted Epic/Feature state changed.
|
||||
7. Add or materially improve at least one useful evidence-based documentation artifact; never create filler solely to satisfy cadence.
|
||||
8. Perform other safe, reversible coordination work when useful.
|
||||
9. Validate Scope menu order, dedicated sidebar hierarchy, identifiers, relationships, links, and the documentation build; verify changes through remote readback.
|
||||
10. Post one concise update with documentation path and commit evidence, or state the concrete blocker that prevented a useful change.
|
||||
10. After CI/readback, scan only the approved channels after this run's per-channel high-watermarks. Keep polling watermarks separate from substantive evidence IDs; read required continuations in full. Reconcile material late decisions against repository state before reporting; boilerplate or a status question alone does not require a new commit.
|
||||
11. Return one concise update with documentation path and commit evidence, or the concrete blocker. If the execution context automatically delivers the final response, do not also send a channel message. Use `[SILENT]` only when that context requests it and no substantive result exists. Claim message delivery/readback only when separately performed and verified; repository readback is not message delivery.
|
||||
|
||||
Source comparison and exclusions: [AeroSim lessons review](references/aerosim-lessons-review.md).
|
||||
|
||||
## Authority and Escalation
|
||||
|
||||
@@ -283,12 +251,12 @@ When a shared coordination PR is refreshed, explicitly fetch its exact source re
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
- [ ] Only the seven same-project channels were inspected.
|
||||
- [ ] Only the eight same-project channels were inspected.
|
||||
- [ ] The update is new, substantive, and deduplicated.
|
||||
- [ ] Overall status, issues, and cross-channel implications are accurate.
|
||||
- [ ] Proposals are clearly labeled and routed.
|
||||
- [ ] Scope appears immediately before Architecture in the top menu and uses its own sidebar.
|
||||
- [ ] Scope sidebar order is Roadmap, Epics with nested Features, then Ideas.
|
||||
- [ ] Scope navigation and hierarchy match the current mapped Scope contract, not a duplicate General specification.
|
||||
- [ ] Roadmap shows current evidence and predicted Epic/Feature plans distinctly and is current.
|
||||
- [ ] Epics and Features use stable `<CODE>-EP-N` and `<CODE>-FT-N` IDs and lifecycle state.
|
||||
- [ ] Every Epic links all child Features with statuses; every Feature links all authoritative tasks with statuses.
|
||||
@@ -298,4 +266,4 @@ When a shared coordination PR is refreshed, explicitly fetch its exact source re
|
||||
- [ ] Guidance changes derive from verified team decisions.
|
||||
- [ ] Completed activities include exact evidence.
|
||||
- [ ] Approval-required actions remain proposals.
|
||||
- [ ] When a bootstrap job is active, its override, seven-channel boundary, frozen high-watermarks, human-message check, General delivery target, and scheduler state are verified.
|
||||
- [ ] When a bootstrap job is active, its override, recorded channel boundary, frozen high-watermarks, human-message check, General delivery target, and scheduler state are verified.
|
||||
@@ -0,0 +1,30 @@
|
||||
# AeroSim lessons review — general
|
||||
|
||||
## Evidence boundary
|
||||
|
||||
Source repository: [corp-v1-aerosim-skills-code-agent/corp-v1-channel-general-aerosim](https://gitea.lego-cloud.eu/corp-v1-aerosim-skills-code-agent/corp-v1-channel-general-aerosim)
|
||||
|
||||
Source commit: `f97a4e8bbc1e107ddff0fac02a6730a32afed56e` (branch `test`, pinned clone; not the earlier adoption-base SHA).
|
||||
|
||||
Central baseline: `e291ea3af85f7656d9293fad510c217ca495df0f`. Reviewed the full source package: `SKILL.md`, `ADOPTION.md`, and `references/shared-coordination-pr-refresh.md`. All existing source reference files were byte-identical to central at baseline; changes below address omissions or contradictions, not wholesale copying.
|
||||
|
||||
The installed `corp-v1-channel-general-aerosim/SKILL.md` was also compared read-only. Runtime SHA-256: `5944a1ba8198f90bca29c186bec8dc173bac006c7cf412dedce9ae0eda53ef58`. Runtime differs from the pinned repository and has no verified source commit for its local-only changes; it is observation, not remote or Board approval evidence. This delegated review did not change any installed package or AeroSim/other project copy. The coordinating session owns authorized central publication and central runtime refresh.
|
||||
|
||||
Review authority: Board-owner request message `1562171939961966693` authorizes central reference improvement and remote publication; the coordinating session also owns the authorized central runtime refresh. Central source publication must be verified before refreshing its installed package. No project adoption, project permission/authority expansion or naming migration is authorized.
|
||||
|
||||
## Adopted lessons
|
||||
|
||||
- `SKILL.md` → **Synchronization Workflow**, steps 6–12 (especially 11–12), and `references/shared-coordination-pr-refresh.md` → **6. Close the channel-activity race** / **7. Scheduled-delivery boundary**: make the existing reference's final convergence and single-delivery checks explicit at the point of execution. Polling watermarks are not substantive evidence. Material late changes require reconciliation, not a stale success report.
|
||||
- `SKILL.md` → **Overview**, **Pending ownership and governance corrections**, and **Kanban Handoff**: preserve domain ownership. Remove the central General copy of Scope navigation/table rules and approval-shaped delivery vocabulary; the pinned central Scope contract already has a different hierarchy and separates gates from delivery. This is conflict removal, not adoption of AeroSim's navigation.
|
||||
|
||||
## Exclusions
|
||||
|
||||
No roster/contact data, named owner assignments, standing merge delegation, blocker-execution authority, board migration, project-local topology overrides or scheduler authorization is imported. Runtime-only **Current AeroSim human roster and work emails — skill-only record**, **Hermes owns blocker resolution**, and **Standing AeroSim PR merge authority** were inspected but not adopted or reproduced. Runtime also differs in board routing and UAT wording; neither is proof of central policy. Existing central bootstrap stop conditions and human gates remain intact.
|
||||
|
||||
## Central topology authority
|
||||
|
||||
The coordinating review record `GUILD-IMP-20261020-aerosim-reference-lessons` confirms central-only maintenance. `corp-v1-main` v4.5.0, **Board Authority** / **Naming Model** / **Hermes access and Corp project automation policy**, records Board message `1552966246591365123` approving eight lifecycle channels, with UAT between Delivery and Releases. Align ordinary synchronization and references to that existing policy. Historical seven-channel bootstrap overrides are not widened; only separately reauthorized overrides may add UAT. Runtime seven-channel wording is stale, not promoted authority.
|
||||
|
||||
## Verification
|
||||
|
||||
Run `python3 -B -m unittest discover -s tests -v` from this repository and `git diff --check`. Tests validate normative documentation contracts and linked files offline; they do not claim live workflow, CI, deployment or remote publication verification.
|
||||
@@ -0,0 +1,41 @@
|
||||
"""Offline regression tests for normative skill-package contracts, not runtime behavior."""
|
||||
from pathlib import Path
|
||||
import re
|
||||
import unittest
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
SKILL = (ROOT / 'SKILL.md').read_text()
|
||||
def ref(name):
|
||||
return (ROOT / 'references' / name).read_text()
|
||||
class Contracts(unittest.TestCase):
|
||||
def test_evidence_and_links(self):
|
||||
self.assertIn('(references/aerosim-lessons-review.md)', SKILL)
|
||||
evidence = ref('aerosim-lessons-review.md')
|
||||
self.assertRegex(evidence, r'Source commit: `[0-9a-f]{40}`')
|
||||
self.assertIn('## Exclusions', evidence)
|
||||
for path in re.findall(r'\]\((references/[^)#]+)(?:#[^)]*)?\)', SKILL):
|
||||
self.assertTrue((ROOT / path).is_file(), path)
|
||||
def test_scope_is_single_contract(self):
|
||||
self.assertIn('Load the mapped Scope skill', SKILL)
|
||||
self.assertNotIn('Minimum Epic Features table', SKILL)
|
||||
self.assertNotIn('Use lifecycle states `Proposed`', SKILL)
|
||||
self.assertIn('not delivery states', SKILL)
|
||||
def test_convergence_precedes_report(self):
|
||||
workflow = SKILL.split('## Synchronization Workflow')[1].split('## Authority')[0]
|
||||
self.assertLess(workflow.index('After CI/readback'), workflow.index('Return one concise update'))
|
||||
for term in ['per-channel high-watermarks', 'substantive evidence IDs', 'continuations in full', 'do not also send a channel message', 'repository readback is not message delivery']:
|
||||
self.assertIn(term, workflow)
|
||||
def test_approval_and_bootstrap_preserved(self):
|
||||
for term in ['Only a human team member', 'first-human-message stop condition', 'no project scheduler', 'eight same-project channels']:
|
||||
self.assertIn(term, SKILL)
|
||||
|
||||
def test_eight_channel_boundary(self):
|
||||
boundary = SKILL.split('## Approved Information Boundary')[1].split('## ', 1)[0]
|
||||
channels = re.findall(r'^corp-v1-<code>-(.+)$', boundary, re.M)
|
||||
self.assertEqual(channels, ['general', 'scope', 'architecture', 'ui-ux', 'kanban', 'delivery', 'uat', 'releases'])
|
||||
self.assertIn('1552966246591365123', boundary)
|
||||
bootstrap = SKILL.split('## Governed bootstrap autonomy')[1].split('## Approved Information Boundary')[0]
|
||||
self.assertIn('Historical seven-channel overrides remain limited', bootstrap)
|
||||
self.assertIn('topology update alone does not expand autonomous scope', bootstrap)
|
||||
|
||||
if __name__ == '__main__':
|
||||
unittest.main()
|
||||
Reference in new issue
Block a user