Scaled-Tech-Consulting/Gitea-Tools
2
0
Fork 0
Code Issues 6 Pull Requests 3 Actions Packages Projects Releases Wiki Activity

docs: require Controller Handoff Summary + codify LLM workflow rules (#101) #102

Merged
sysadmin merged 1 commits from docs/issue-101-controller-handoff-workflow into master 2026-07-02 17:25:26 -05:00
Conversation 0 Commits 1 Files Changed 4
+182 -4
sysadmin commented 2026-07-02 17:17:46 -05:00
Owner
Copy Link
Copy Source

Implements #101. Documentation/skills only — captures the workflow rules proven during the v1.1.0 completion cycle.

Summary

  • skills/llm-project-workflow/SKILL.md
    • New §K Controller Handoff Summary — required at the end of EVERY task (implementation, review, merge, triage, docs, discussion-only, blocked planning); exact required format verbatim + hard rules (never omit, never bury blockers, name the exact blocking gate, report touched tag/commit) + worked blocked-handoff example (the real mcp-control-plane case).
    • §A issue-first extended: discussion/RFC issues for design-only work (no branches/PRs from discussion tasks; comments carry recommendations/risks/questions + handoff summary); stop and ask when tracker home unclear; no new repo/tracker without explicit owner approval.
    • §G merge workflow: identity + PR-author verification, runtime profile gates, independent validation, pinned head SHA + expected changed-file set merges.
    • Versioning: no tag create/move/delete/push unless instructed; tag only the verified final master merge commit after the PR merges; always report the tag target.
    • "§A–§I project-agnostic" → §A–§K.
  • docs/llm-workflow-runbooks.md — new "Controller Handoff Summary (required, every task)" section pointing at SKILL §K; notes design debates belong in discussion issues (e.g. #100 profiles.json v2 — mentioned only, not modified).
  • Templates start-issue.md / review-pr.md — handoff lines now require the §K format ("Review needed — PR is open" / name the exact blocking gate).

Files changed

4 files, +182/−4 (all markdown).

Validation

  • py_compile mcp_server.py manage_labels.py gitea_auth.py — OK (no code touched; sanity)
  • bash -n scripts/clear-provenance — OK
  • pytest tests/ -q — 357 passed, 6 skipped
  • git diff --check — clean
  • Staged-diff secret sweep — clean
  • (No markdown linter in repo.)

Risks

Documentation drift only — SKILL §K duplicates the format the owner mandated; future format changes must update SKILL + runbooks together. No behavior change anywhere.

Confirmations

  • No release/tag state changed (v1.0.0/v1.0.1/v1.1.0 untouched).
  • #100 not modified (referenced as the discussion-issue example only).
  • No mcp-control-plane creation, no phase-2 issues, no profiles.json v2 work.

Closes #101.

Controller Handoff Summary

Work performed

Documented the mandatory Controller Handoff Summary (§K) and six workflow rule groups (issue-first/discussion-RFC/review-merge/release-tag/branch-worktree/blocked-handling) across the portable skill, runbooks, and two templates.

Current state

  • Repo: Scaled-Tech-Consulting/Gitea-Tools
  • Branch: docs/issue-101-controller-handoff-workflow @ f09791e (from master cdc3266)
  • Issue: #101 (claimed, status:in-progress, labels documentation/workflow/mcp)
  • PR: this one — ready for review

Files changed

skills/llm-project-workflow/SKILL.md, docs/llm-workflow-runbooks.md, skills/llm-project-workflow/templates/start-issue.md, skills/llm-project-workflow/templates/review-pr.md

Validation

py_compile ×3 OK · bash -n OK · pytest 357 passed/6 skipped · diff --check clean · secret sweep clean

Issues encountered

None. (llm label doesn't exist; used closest existing labels per instruction — no labels created.)

Review needed?

Independent non-author review needed

Next recommended action

Non-author reviewer (identity ≠ this PR's Gitea author) reviews and merges; auto-close releases #101.

Safety confirmations

  • no self-review ✓ · no self-merge ✓ · no release/tag changes ✓ · no secrets committed ✓ · no production access used ✓

LLM Handoff Metadata:

  • LLM-Agent-SHA: llm-ab5bccf566fc
  • LLM-Role: implementer
  • Authenticated-Gitea-User: sysadmin (MCP session; branch commits authored via jcwalker3 CLI)
  • MCP-Profile: prgs-reviewer
  • Branch: docs/issue-101-controller-handoff-workflow
  • Worktree: branches/docs-issue-101-controller-handoff-workflow
  • Self-review allowed: no

🤖 Generated with Claude Code

Implements #101. Documentation/skills only — captures the workflow rules proven during the v1.1.0 completion cycle. ## Summary - **`skills/llm-project-workflow/SKILL.md`** - New **§K Controller Handoff Summary** — required at the end of EVERY task (implementation, review, merge, triage, docs, discussion-only, blocked planning); exact required format verbatim + hard rules (never omit, never bury blockers, name the exact blocking gate, report touched tag/commit) + worked **blocked-handoff example** (the real `mcp-control-plane` case). - §A issue-first extended: discussion/RFC issues for design-only work (no branches/PRs from discussion tasks; comments carry recommendations/risks/questions + handoff summary); **stop and ask when tracker home unclear; no new repo/tracker without explicit owner approval**. - §G merge workflow: identity + PR-author verification, runtime profile gates, independent validation, **pinned head SHA + expected changed-file set** merges. - Versioning: no tag create/move/delete/push unless instructed; tag only the verified final master merge commit after the PR merges; always report the tag target. - "§A–§I project-agnostic" → §A–§K. - **`docs/llm-workflow-runbooks.md`** — new "Controller Handoff Summary (required, every task)" section pointing at SKILL §K; notes design debates belong in discussion issues (e.g. #100 `profiles.json v2` — mentioned only, not modified). - **Templates** `start-issue.md` / `review-pr.md` — handoff lines now require the §K format ("Review needed — PR is open" / name the exact blocking gate). ## Files changed 4 files, +182/−4 (all markdown). ## Validation - `py_compile mcp_server.py manage_labels.py gitea_auth.py` — OK (no code touched; sanity) - `bash -n scripts/clear-provenance` — OK - `pytest tests/ -q` — **357 passed, 6 skipped** - `git diff --check` — clean - Staged-diff secret sweep — clean - (No markdown linter in repo.) ## Risks Documentation drift only — SKILL §K duplicates the format the owner mandated; future format changes must update SKILL + runbooks together. No behavior change anywhere. ## Confirmations - No release/tag state changed (v1.0.0/v1.0.1/v1.1.0 untouched). - #100 not modified (referenced as the discussion-issue example only). - No `mcp-control-plane` creation, no phase-2 issues, no `profiles.json v2` work. Closes #101. ## Controller Handoff Summary ### Work performed Documented the mandatory Controller Handoff Summary (§K) and six workflow rule groups (issue-first/discussion-RFC/review-merge/release-tag/branch-worktree/blocked-handling) across the portable skill, runbooks, and two templates. ### Current state - Repo: `Scaled-Tech-Consulting/Gitea-Tools` - Branch: `docs/issue-101-controller-handoff-workflow` @ `f09791e` (from master `cdc3266`) - Issue: #101 (claimed, `status:in-progress`, labels documentation/workflow/mcp) - PR: this one — ready for review ### Files changed `skills/llm-project-workflow/SKILL.md`, `docs/llm-workflow-runbooks.md`, `skills/llm-project-workflow/templates/start-issue.md`, `skills/llm-project-workflow/templates/review-pr.md` ### Validation py_compile ×3 OK · bash -n OK · pytest 357 passed/6 skipped · diff --check clean · secret sweep clean ### Issues encountered None. (`llm` label doesn't exist; used closest existing labels per instruction — no labels created.) ### Review needed? Independent non-author review needed ### Next recommended action Non-author reviewer (identity ≠ this PR's Gitea author) reviews and merges; auto-close releases #101. ### Safety confirmations - no self-review ✓ · no self-merge ✓ · no release/tag changes ✓ · no secrets committed ✓ · no production access used ✓ LLM Handoff Metadata: - LLM-Agent-SHA: llm-ab5bccf566fc - LLM-Role: implementer - Authenticated-Gitea-User: sysadmin (MCP session; branch commits authored via jcwalker3 CLI) - MCP-Profile: prgs-reviewer - Branch: docs/issue-101-controller-handoff-workflow - Worktree: branches/docs-issue-101-controller-handoff-workflow - Self-review allowed: no 🤖 Generated with [Claude Code](https://claude.com/claude-code)
sysadmin added 1 commit 2026-07-02 17:17:46 -05:00
docs: require Controller Handoff Summary + codify LLM workflow rules (#101) f09791e049 
- SKILL.md: new §K Controller Handoff Summary (required every task type)
  with the exact format and a worked blocked-handoff example; issue-first
  rule extended (discussion/RFC issues, unclear-tracker-home stop rule, no
  new repo/tracker without owner approval); merge workflow now names
  identity+author verification, profile gates, independent validation, and
  pinned head SHA / expected changed-file merges; tagging rules extended
  (no tag ops unless instructed, tag only the verified final master merge
  commit, always report tag target).
- llm-workflow-runbooks.md: Controller Handoff Summary section pointing at
  SKILL §K, incl. discussion/RFC rule (e.g. #100 stays a discussion issue).
- templates/start-issue.md + review-pr.md: handoff lines now reference the
  required summary format and the exact-gate reporting rule.

Docs only; no code behavior changed. No tags touched; #100 not modified.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
sysadmin merged commit 790c2c80b1 into master 2026-07-02 17:25:26 -05:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
architecture
Architecture / structural design
 bug
chore
design
Design / investigation, no implementation
 documentation
Docs / runbooks
 enhancement
New feature or improvement
 gitea
Gitea MCP workflow
 glitchtip
GlitchTip integration
 important
integration
Integration testing
 jenkins
Jenkins integration
 labels
Label taxonomy management
 mcp
MCP server / tooling
 mutating
Mutating action; requires gating
 nice-to-have
portability
Cross-platform / portability
 read-only
Read-only, no mutation
 refactor
Code refactor / restructure
 release
Release / versioning
 reliability
Reliability / failure handling
 roadmap
Roadmap / umbrella issue
 security
Security / trust boundary
 status:in-progress
Issue is being worked on
 testing
Tests / test coverage
 tracker
Issue tracker hygiene / meta
 workflow
Cross-tool workflow
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
jcwalker3 sysadmin
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#102
Delete Branch "docs/issue-101-controller-handoff-workflow"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?