@jaybeeuu/agent-cortex 2.1.0 → 2.3.0

package/skills/style/style-comms/SKILL.md

@@ -72,14 +72,12 @@ description: Sets tone, structure, and concision rules for written communication
 |---|---|
 | "This might potentially cause some issues that we could look at." | "This approach causes two problems: increased latency and a single point of failure." |
 
-## Cross-skill references
+## See Also
 
-| When you need… | Use this skill |
-|---|---|
-| A document template with section structure | `write-a-ticket`, `write-a-prd`, `write-a-skill` |
-| Guidance on what and whether to document | `style-documentation` |
-| Coding style and conventions | `style-code` |
-| Test writing style | `style-tests` |
+- [style-documentation](../style-documentation/SKILL.md) — what and whether to document, decided before the prose choices here.
+- [write-a-prd](../../planning/write-a-prd/SKILL.md) — the section structure for a requirements document.
+- [write-a-ticket](../../planning/write-a-ticket/SKILL.md) — the section structure for an external ticket.
+- [write-a-skill](../../productivity/write-a-skill/SKILL.md) — the section structure for a SKILL.md.
 
 ## Verification checklist
 

package/skills/style/style-documentation/SKILL.md

@@ -70,13 +70,12 @@ description: Defines what to document, what to skip, and how to structure docume
 | "This is obvious from the code" | Then do not write it. The code is the documentation — let it do the work. |
 | "This doc is harmless even if it drifts" | Drift is not harmless — it erodes trust. Every stale sentence makes the reader wonder what else is wrong. Prune or update instead. |
 
-## Cross-skill references
+## See Also
 
-| When you need… | Use this skill |
-|---|---|
-| Tone, structure, and concision for writing | `style-comms` |
-| Code-level conventions and inline comments | `style-code` |
-| Secrets and credential scanning before committing | `review-security` |
+- [maintain-agent-docs](../../review/maintain-agent-docs/SKILL.md) — load when auditing existing docs for drift rather than writing new pages.
+- [style-comms](../style-comms/SKILL.md) — tone, structure, and concision for the prose itself.
+- [style-code](../style-code/SKILL.md) — code-level conventions, including doc comments and examples.
+- [review-security](../../review/review-security/SKILL.md) — run before committing, so examples stay secret-free.
 
 ## Examples
 

package/skills/style/style-tests/SKILL.md

@@ -106,14 +106,12 @@ Worked examples for each rule are in `EXAMPLES.md` under _Test data_.
 | "A shared fixture saves setup time" | It couples tests and hides which value drives the case. Build data fresh per test. |
 | "Asserting every field is more thorough" | It makes the test break for reasons the case does not care about. Assert the fields that prove the behaviour. |
 
-## Cross-skill references
+## See Also
 
-| When you need… | Use this skill |
-|---|---|
-| Red-green-refactor development loop | `tdd` |
-| Code-level style and conventions | `style-code` |
-| Plan test rows that gate implementation | `plan` |
-| Secrets and credential scanning | `review-security` |
+- [tdd](../../engineering/tdd/SKILL.md) — the red-green loop these conventions serve; load it for slicing and cycle discipline.
+- [style-code](../style-code/SKILL.md) — naming and module-boundary rules for the code under test.
+- [plan](../../workflow/plan/SKILL.md) — load when test rows should gate implementation planning rather than code.
+- [review-security](../../review/review-security/SKILL.md) — run before committing, when fixtures risk carrying real credentials.
 
 ## Examples
 

package/skills/workflow/git-workflow/SKILL.md

@@ -46,7 +46,31 @@ working on the same thing, use a shared branch and workspace instead.
 not spin up a separate worktree — work in the same checkout so you both see
 the same state.
 
-### 3. Pull requests for review
+### 3. Never stack branches — put the dependency in the tracker
+
+Every branch is based on the **integration branch**: `main`, or `epic/<id>` for
+multi-feature work. Never base one feature branch on another.
+
+```
+❌ git worktree add ../b -b feature/b feature/a    # b silently carries a
+✅ git worktree add ../b -b feature/b origin/main
+```
+
+If `b` needs `a`, that is a **dependency**, not a branch. Record it in the
+tracker — `bd dep add <b> <a>` ("b depends on a") — and let the tracker keep `b`
+out of the ready queue until `a` merges and closes. Then branch `b` from the
+integration branch, which by then contains `a`.
+
+Why: this repo squash-merges, so `feature/a`'s commits never become ancestors of
+the integration branch. The moment `a` merges, `b` carries all of `a`'s content
+as if it were new work, GitHub reports `CONFLICTING` on byte-identical files, and
+the repair costs a `git rebase --onto <integration> <old-base>` plus a full
+re-verification. Waiting for the merge is always cheaper.
+
+Wanting to "get ahead" while a dependency is in review is the signal the
+dependency is real — stop and check the tracker instead.
+
+### 4. Pull requests for review
 
 Every feature branch ends in a GitHub PR. Open the PR early (draft if unfinished) so the diff is visible.
 
@@ -55,7 +79,7 @@ gh pr create --title "..." --body "..."
 gh pr create --draft  # early
 ```
 
-### 4. Sync before branching
+### 5. Sync before branching
 
 Before creating a feature branch, sync with upstream:
 
@@ -66,41 +90,43 @@ git pull
 
 This avoids avoidable merge conflicts.
 
-### 5. Bring a behind branch up to date — merge, don't rebase
+### 6. Bring a behind branch up to date — rebase, don't merge
 
-When the base branch moves and the PR reports `BEHIND` or `CONFLICTING`, update
-the branch before anything else:
+When the base branch moves and the PR reports `BEHIND` or `CONFLICTING`, rebase
+your branch onto its base branch before anything else — never merge the base in:
 
 ```bash
 git fetch origin
-git merge origin/main
+git rebase origin/main        # or epic/<id> for a feature branch inside an epic
+git push --force-with-lease
 ```
 
-**Never rebase a branch that contains a merge commit.** `git rebase` drops merge
-commits and the patches they carry, so rebasing a branch that already merged the
-base silently reverts what that merge resolved — the conflict resolutions, and
-any fix from the base the merge brought in. The result usually looks like a
-regression in your own change. `--rebase-merges` preserves the structure, but
-it re-opens the same conflicts; only worth it when the branch's history is
-itself the deliverable.
+A merge from the base drags every intervening commit into the review diff and,
+under a squash-merge landing method, contributes nothing that reaches the base
+branch. Landing is still a squash merge; rebasing only reshapes *your* branch
+before it lands, so these are separate decisions, not rivals. Keeping the branch
+linear is what makes the rebase safe: `git rebase` drops merge commits and the
+patches they resolved, so never rebase a branch that already merged the base.
 
-Rebase only a **linear branch that has not been reviewed yet**. Rewriting
-commits under review discards the review context and invalidates approvals, and
-it requires `git push --force-with-lease` — never `--force`, which overwrites
-work you have not seen.
+One exception: an **integration branch** that other branches are based on
+(`main`, or an `epic/<id>` branch) is not yours to rewrite. Sync it by merging
+the base in — under squash-merge that merge never reaches the landing diff, and
+the branches based on it stay linear by rebasing onto it.
 
-Which one you owe the repository depends on its landing method, not on taste:
+Rewritten commits are re-signed automatically when `commit.gpgsign` is set. Pass
+no `--gpg-sign`, and do not set `rebase.gpgSign` — both are redundant.
 
-- **Squash merge**: the branch is collapsed on landing, so its shape never
-  reaches the base branch. Merge the base in and move on — rebasing here is
-  cosmetic, and the risky kind of cosmetic.
-- **Rebase-and-merge**: a linear branch is mandatory, so rebase *before* the
-  first review. Once a merge has landed on the branch, that option is gone.
+Scope: rebase only your **own unmerged feature branch**. Never rebase `main` or an
+`epic/<id>` branch others are based on, and never rebase a branch another person
+or agent is working on — it discards their context and invalidates review.
+Force-push with `--force-with-lease`, never `--force`, which overwrites work you
+have not seen. Rewriting a reviewed branch discards the review context and
+invalidates approvals, so re-request review after a sync.
 
-After any update, re-run the checks. A merge that resolved conflicts by hand is
-not verified by the base branch's green CI.
+After any update, re-run the checks: a conflict resolved by hand is not verified
+by the base branch's green CI.
 
-### 6. Worktree lifecycle
+### 7. Worktree lifecycle
 
 After the PR is merged or closed, clean up the worktree:
 

package/skills/workflow/hitl-collab/SKILL.md

@@ -55,13 +55,11 @@ Use these sections in this order, adapting headings to the task:
 
 - **Docs are the durable artifact; bead updates are pointers.** The document outlives the session and the worktree, so the human gate always has a stable review surface. The bead carries only what routing needs — links and the doc path.
 
-## Cross-skill references
+## See Also
 
-| When you need… | Use this skill |
-|---|---|
-| Tone, structure, and concision for the doc | `style-comms` |
-| Conversation compaction for another agent | `handoff` |
-| Bead discovery, queries, and state updates | `bd-tool` |
+- [style-comms](../../style/style-comms/SKILL.md) — tone, structure, and concision for the handoff doc.
+- [handoff](../../productivity/handoff/SKILL.md) — load when the reader is another agent rather than a human.
+- [bd-tool](../../productivity/bd-tool/SKILL.md) — bead discovery, queries, and the state updates the doc links from.
 
 ## Examples
 

package/skills/workflow/plan/SKILL.md

@@ -63,7 +63,7 @@ section content; surface assumptions and confirm them with the user.
 
 7. Create an epic bead from the approved PRD:
    ```bash
-   bd create "<Feature Title> — PRD" --type epic \
+   bd create "<Feature Title> — PRD" --type epic -l execution:hitl \
      --description "<rendered PRD as markdown>" --priority p2 --validate
    bd tag <epic-id> workflow:plan
    bd lint <epic-id>
@@ -91,7 +91,7 @@ Take the approved PRD and produce a set of epics and tasks using tracer-bullet v
 
 10. If the work is small enough for a single epic (one phase, a few tasks), skip epics and proceed directly to Phase 3. A single epic with a few tasks dispatches through ralph more efficiently than creating unnecessary epic hierarchy. If the work has multiple distinct phases, create epics:
     ```bash
-    bd create "<Phase Title>" --type epic \
+    bd create "<Phase Title>" --type epic -l execution:hitl \
       --description "<epic body with scope, success criteria, dependencies>" --priority <same as parent> --validate
     bd tag <epic-id> workflow:plan
     bd lint <epic-id>
@@ -119,19 +119,30 @@ For each task (within each epic), create a bead, classify it, and expand AFK tas
     ```bash
     # create-task handles: bead creation → classify → AFK: expand into pipeline stages → HITL: stop
     ```
-    Pass the parent epic ID (if epics are used) so tasks are nested under their epic.
+    Pass the parent epic ID (if epics are used) so tasks are nested under their epic — `--parent`
+    records ownership. Work that needs sequencing instead of nesting gets `bd dep add`.
 
-14. After all tasks in an epic are created, tag the parent epic with the aggregate classification:
-    - If **any** task is HITL: `bd tag <epic-id> implementation-type:hitl`
-    - If **all** tasks are AFK: `bd tag <epic-id> implementation-type:afk`
+14. When a task in the breakdown is really several deliverables, create it with the feature shape
+    rather than fattening it: a feature bead (`execution:hitl`) owning one planning bead
+    (`execution:hitl`, "Plan: <title>") that blocks one `execution:afk` impl child per deliverable.
+    `create-task` steps 5–6 run this sequence; the planning bead's description carries the
+    cold-start contract (what and why, decisions made, open questions, references).
 
-15. Present the full bead tree to the user:
+15. Do not aggregate a child's execution class onto its parent. An epic or feature is a container
+    that a human owns, so it is `execution:hitl` in its own right; each task states its own
+    `execution:afk` or `execution:hitl`. Copying `execution:afk` upward because every child is AFK
+    labels a human-owned container as agent work.
+
+16. Present the full bead tree to the user:
     ```
-    Epic: "Phase 1 Title" (#epic-abc)
+    Epic: "Phase 1 Title" (#epic-abc) — HITL
       ├── Task 1: "..." (#task-123) — AFK
       ├── Task 2: "..." (#task-456) — HITL (visual review)
-      └── Task 3: "..." (#task-789) — AFK
-    Epic: "Phase 2 Title" (#epic-def)
+      ├── Task 3: "..." (#task-789) — AFK
+      └── Feature 4: "..." (#feat-012) — HITL
+            ├── Plan: Feature 4 (#task-013) — HITL, blocks #task-014
+            └── Task 5 (#task-014) — AFK
+    Epic: "Phase 2 Title" (#epic-def) — HITL
       ├── ...
     ```
 
@@ -140,14 +151,15 @@ For each task (within each epic), create a bead, classify it, and expand AFK tas
 - [ ] All tasks created via `create-task`
 - [ ] All tasks classified (AFK or HITL)
 - [ ] AFK tasks expanded into pipeline-stage chore beads plus PR gate
-- [ ] Parent epics tagged with aggregate `implementation-type`
+- [ ] Epics and features carry `execution:hitl`; no execution label aggregated from children
 - [ ] Full bead tree presented to the user
 
 ### Phase 4 — Prepare handoff to ralph
 
 Deliver a handoff bead and instructions for running ralph.
 
-16. Determine the entry point:
+17. Determine the entry point:
+
     - **Single epic**: the epic ID is the handoff bead.
     - **Multiple independent epics**: create a parent meta-epic that groups them:
       ```bash
@@ -157,7 +169,7 @@ Deliver a handoff bead and instructions for running ralph.
 ## Success Criteria
 
 - [ ] All child epics complete and the feature verified end-to-end." \
-        --priority <same> --validate
+        --priority <same> -l execution:hitl --validate
       bd lint <meta-epic>
       bd dep add <epic-1> <meta-epic> --type parent-child
       bd dep add <epic-2> <meta-epic> --type parent-child
@@ -165,17 +177,18 @@ Deliver a handoff bead and instructions for running ralph.
       The meta-epic ID is the handoff bead.
     - **Sequentially dependent epics**: the first unblocked epic is the handoff bead — ralph will discover the rest via `bd ready` as dependencies clear.
 
-17. Tag the handoff bead for ralph's discovery:
+18. Tag the handoff bead for ralph's discovery:
     ```bash
     bd tag <handoff-id> workflow:ralph
     ```
 
-18. Push the bead state:
+19. Push the bead state:
     ```bash
     bd dolt push
     ```
+    **Gate on the exit status.** Non-zero: retry once, then stop and report the command, exit code and stderr as a sync blocker — the handoff has not left this machine, so do not present the handoff summary.
 
-19. Present the handoff summary:
+20. Present the handoff summary:
     ```
     ✅ Plan complete. Ready for ralph.
 
@@ -189,7 +202,7 @@ Deliver a handoff bead and instructions for running ralph.
 
     | Bead ID | Title | Type | Classification |
     |---------|-------|------|---------------|
-    | #epic   | Phase 1 | epic | AFK |
+    | #epic   | Phase 1 | epic | HITL |
     | #task   | Task 1 | task | AFK (4 chore beads + PR gate) |
     | #task   | Task 2 | task | HITL |
     | ...     | ...    | ...  | ... |
@@ -199,7 +212,7 @@ Deliver a handoff bead and instructions for running ralph.
 
 - [ ] Handoff bead identified and tagged `workflow:ralph`
 - [ ] Every handoff-path bead lints clean (`bd lint`)
-- [ ] Bead state pushed with `bd dolt push`
+- [ ] Bead state pushed with `bd dolt push`, and the push exited 0 — a non-zero exit was retried once, then surfaced as a blocker (command, exit code, stderr) with no handoff summary presented
 - [ ] Handoff summary presented with the exact instruction to give an agent
 
 ## Phase-gate checklist
@@ -232,16 +245,13 @@ Deliver a handoff bead and instructions for running ralph.
 - **Planning and execution are separate concerns.** The plan skill works with the user to get the right scope and structure. Ralph then executes autonomously within that structure. Separating them means the user reviews once, not piecemeal.
 - **AFK by default.** Classify tasks as AFK unless a human is genuinely required. Agent capability grows over time — tasks that feel HITL today may be AFK tomorrow.
 
-## Cross-skill references
+## See Also
 
-- `write-a-prd` — PRD template and interview workflow for Phase 1 (this skill incorporates the approach inline rather than delegating, to maintain a single coherent conversation).
-- `prd-to-tasks` — For the task breakdown step in Phase 2. If the PRD is already written and only decomposition is needed, use that skill directly.
-- `create-task` — Invoked in Phase 3 for each task. Handles bead creation, classification via `classify-bead`, and pipeline expansion for AFK tasks.
-- `classify-bead` — Invoked internally by `create-task`; not invoked directly by this skill.
-- `ralph` — The downstream skill that consumes the handoff bead. Run a separate agent with "Use the ralph skill. Start from bead #<handoff-id>."
-- `record-idea` — Use this instead if the idea is not ready for implementation planning.
-- `style-comms` — Invoke during Phase 1 if the user stories or implementation decisions need clearer writing.
-- `style-documentation` — Invoke during Phase 1 to align PRD documentation conventions with project standards.
+- [write-a-prd](../../planning/write-a-prd/SKILL.md) — owns the PRD template and interview workflow that Phase 1 folds in.
+- [prd-to-tasks](../../planning/prd-to-tasks/SKILL.md) — load when the PRD is already written and only decomposition is needed.
+- [spec-to-tickets](../../planning/spec-to-tickets/SKILL.md) — load instead when the PRD must become external tickets rather than beads.
+- [create-task](../../planning/create-task/SKILL.md) — Phase 3's per-task bead creation and pipeline expansion; it invokes `classify-bead` internally, so this skill never classifies directly.
+- [ralph](../ralph/SKILL.md) — the downstream consumer of the handoff bead — hand off by running a separate agent with "Use the ralph skill. Start from bead #<handoff-id>".
 
 ## Examples
 
@@ -261,7 +271,7 @@ Full bead tree:
 
 | Bead ID | Title | Type | Classification |
 |---------|-------|------|---------------|
-| #epic-abc123  | Webhook Notification System — PRD | epic | AFK |
+| #epic-abc123  | Webhook Notification System — PRD | epic | HITL |
 | #task-456 | Create webhook subscription schema + API | task | AFK (4 chore beads + PR gate) |
 | #task-789 | Implement event dispatch and retry logic | task | AFK (4 chore beads + PR gate) |
 | #task-012 | Build subscriber management UI | task | HITL (visual review) |
@@ -277,8 +287,9 @@ Full bead tree:
 - [ ] Task breakdown uses vertical slices (each task covers all layers — schema, API, logic, UI if applicable, tests)
 - [ ] Task breakdown approved by the user before moving to Phase 3
 - [ ] All tasks created via `create-task` (which handles classification, pipeline expansion, and PR gate creation)
-- [ ] Parent epics tagged with aggregate `implementation-type` (AFK if all children AFK, HITL if any child is HITL)
+- [ ] Epics and features carry `execution:hitl`; every task states its own `execution:afk`/`execution:hitl`
+- [ ] No execution label aggregated from children onto a parent
 - [ ] Full bead tree presented to the user before handoff
 - [ ] Handoff bead tagged `workflow:ralph`
-- [ ] Bead state pushed with `bd dolt push`
+- [ ] Bead state pushed with `bd dolt push`, and the push exited 0 — a non-zero exit was retried once, then surfaced as a blocker (command, exit code, stderr) with no handoff summary presented
 - [ ] Handoff summary includes the exact instruction to give an agent