clikit-plugin 0.2.47 → 0.3.0

package/AGENTS.md

@@ -10,16 +10,16 @@ The plugin (`src/index.ts`) loads agents from `src/agents/*.md`, commands from `
 
 **Quick mode** (simple features):
 ```
-/create → /start → /ship → /verify
+/create → /start → /verify → /ship
 ```
 
 **Deep mode** (complex features, research, UI):
 ```
-/create → /research → /design → /start → /ship → /verify
+/create → /research → /design → /start → /verify → /ship
 ```
 
 - `/create` produces both spec and plan — `/start` works directly from this output
-- `/verify` is the pre-ship gate — run before `/ship` finalizes
+- `/verify` is the pre-ship gate — run before `/ship` finalizes and lands shared-checkout changes
 - `/research` = external docs, API comparison, library research
 - `/design` = UI/UX design and implementation (uses Vision agent)
 
@@ -68,7 +68,7 @@ bun run dev        # watch mode
 ### Agent Core Cycle
 
 ```
-beads-village_init → beads-village_add → beads-village_claim → reserve → work → done
+beads-village_init → inspect shared git state → beads-village_add → beads-village_claim → reserve → work → done
 ```
 
 In compressed workflow, the execution unit is a **Task Packet**:
@@ -106,5 +106,8 @@ In compressed workflow, the execution unit is a **Task Packet**:
 - Trivial (< 2 min, 1-line fix): skip Beads, just do it
 - Non-trivial: create issue first → claim → work → done
 - `todowrite` = in-session UI display only — Beads is the persistent and authoritative execution state
+- Work in the shared checkout on the repo default branch — no git worktrees or per-task branches unless the user explicitly requests them
+- Check `git status --short --branch` before editing; if overlapping local changes already exist in your scope, stop and coordinate instead of isolating the work
+- Use `beads-village_reserve` to surface conflicts early in the shared workspace
 - Always `reserve` files before editing in multi-agent contexts
-- Always `done` before ending session (releases file locks)
+- Call `done` before ending a completed session; for mid-task handoff, leave the issue open and hand off without `done`

package/README.md

@@ -8,7 +8,7 @@ Curated agents, commands, skills, and memory system for OpenCode.
 - **15 Slash Commands**: /create, /start, /ship, /verify, /debug, /design, /research, /commit, /pr, and more
 - **22 Workflow Skills**: TDD, debugging, research, integrations, ritual-workflow, and more
 - **7 Internal Utilities**: memory (read/search/get/timeline/update/admin), observation, context-summary, cass-memory (used by hooks, not directly registered as agent tools)
-- **10 Runtime Hooks**: todo enforcer, empty output sanitizer, git guard, security check, subagent blocker, truncator, memory digest, todo→beads sync, beads-context, and cass-memory
+- **10 Runtime Hooks/Modules**: todo enforcer, empty output sanitizer, git guard, security check, subagent blocker, truncator, memory digest, todo→beads sync, beads-context, and cass-memory
 - **Memory System**: Templates, specs, plans, research artifacts with FTS5 search
 - **Extended Permissions**: doom_loop, external_directory controls
 - **Configurable**: Enable/disable agents, override models, customize behavior
@@ -84,12 +84,12 @@ After installation, use these commands:
 
 **Quick mode** (simple features):
 ```
-/create → /start → /ship → /verify
+/create → /start → /verify → /ship
 ```
 
 **Deep mode** (complex features, research, UI):
 ```
-/create → /research → /design → /start → /ship → /verify
+/create → /research → /design → /start → /verify → /ship
 ```
 
 Workflow notes:
@@ -97,7 +97,7 @@ Workflow notes:
 - `/create` explores codebase first, then produces both spec and plan
 - `/start` executes the plan, one Task Packet at a time — creates a minimal inline plan if none exists
 - `/verify` runs all 4 gates (typecheck, tests, lint, build) + deep review — use anytime, not just pre-ship
-- `/ship` finalized work and creates PR — runs self-review standalone, recommended to run `/verify` first
+- `/ship` finalizes work in the shared checkout — commit, sync, and land on the repo default branch; `/pr` is optional and only for explicit PR-based exceptions
 - `/research` conducts external research — use standalone before any complex implementation
 - `/design` implements UI/UX with variant exploration and a11y — uses Vision agent
 - Beads is the live execution source of truth
@@ -220,7 +220,7 @@ Run with `/command-name` in OpenCode. **All 15 commands work standalone** — th
 | `/research` | ✅ | Deep-dive any library, API, or pattern with saved report |
 | `/design` | ✅ | UI/UX design + implementation — variant exploration, a11y, responsive (Vision agent) |
 | `/start` | ✅ | Execute plan packets — creates minimal inline plan if none exists |
-| `/ship` | ✅ | Commit + create PR — self-review built in, `/verify` recommended |
+| `/ship` | ✅ | Commit + land shared-checkout changes on the default branch — self-review built in, `/verify` recommended |
 | `/verify` | ✅ | Full 4-gate check (typecheck, tests, lint, build) + deep code review |
 
 ### Utilities (all standalone)
@@ -233,13 +233,15 @@ Run with `/command-name` in OpenCode. **All 15 commands work standalone** — th
 | `/handoff` | Auto-capture session state for graceful pause |
 | `/resume` | Pick up cold from latest handoff, no warm-up questions |
 | `/commit` | Auto-detect type/scope → perfect Conventional Commit message |
-| `/pr` | Full PR description from git diff, linked to spec/plan/bead |
+| `/pr` | Optional PR flow for explicit branch-based review exceptions |
 | `/import-plan` | Import Jira/Notion/Linear tasks → Beads issues + plan |
 
 ## Skills
 
 22 workflow skills organized into 5 categories:
 
+> `using-git-worktrees` and `finishing-a-development-branch` are legacy skill names kept for compatibility. Their current guidance follows the shared-workspace, direct-to-default-branch workflow.
+
 ### Planning & Workflow (4)
 | Skill | Use When |
 |-------|----------|
@@ -253,8 +255,8 @@ Run with `/command-name` in OpenCode. **All 15 commands work standalone** — th
 |-------|----------|
 | `deep-research` | Exploring unfamiliar code or complex features |
 | `source-code-research` | API docs insufficient, need library internals |
-| `using-git-worktrees` | Isolated workspace on new branch |
-| `finishing-a-development-branch` | Completing work on a branch |
+| `using-git-worktrees` | Legacy alias — shared checkout on the default branch, no worktrees |
+| `finishing-a-development-branch` | Legacy alias — finish and land from the shared default-branch workspace |
 
 ### Testing & Quality (5)
 | Skill | Use When |
@@ -315,7 +317,7 @@ bun run dev
 │   ├── agents/       # Agent loaders
 │   ├── skills/       # Skill loaders
 │   ├── tools/        # Internal utilities (memory, context-summary, cass-memory)
-│   └── hooks/        # Runtime hooks (9 modules)
+│   └── hooks/        # Runtime hooks (10 modules)
 ├── skill/            # Skill definitions (*.md)
 ├── command/          # Command definitions (*.md)
 ├── memory/           # Memory system

package/command/pr.md

@@ -1,13 +1,15 @@
 ---
-description: Generate a complete PR description from git diff — summary, file changes, test evidence, linked spec/plan — then create it via gh.
+description: Optional branch-based utility. Generate a complete PR description from git diff — summary, file changes, test evidence, linked spec/plan — then create it via gh when the user or repo policy explicitly requires a PR.
 agent: build
 ---
 
 You are creating a **pull request** with comprehensive description.
 
+This is an **exception flow**. The default shared-workspace policy lands changes directly on the repo default branch without creating a PR.
+
 ## Your Task
 
-Generate a well-structured PR with context, changes, and testing info.
+Generate a well-structured PR with context, changes, and testing info — but only when the user explicitly asks for a PR or the repo policy requires one.
 
 ## Process
 
@@ -17,16 +19,22 @@ Generate a well-structured PR with context, changes, and testing info.
 # Current branch
 git branch --show-current
 
-# Commits to include
-git log main..HEAD --oneline
+# Shared workspace state
+git status --short --branch
+
+# Remote / default branch info (if configured)
+git remote show origin
 
-# Files changed
-git diff main --stat
+# Commits to include (replace <default-branch> after detection)
+git log <default-branch>..HEAD --oneline
+
+# Files changed against default branch
+git diff <default-branch> --stat
 
-# Target branch
-git remote show origin | grep "HEAD branch"
 ```
 
+If you are still on the shared default branch, stop and ask before proceeding — PR flow requires a dedicated branch and explicit user approval.
+
 ### 2. Load Artifacts
 
 - `spec.md` — Link requirements
@@ -42,7 +50,7 @@ git remote show origin | grep "HEAD branch"
 gh pr create \
   --title "[type]: [description]" \
   --body "[generated body]" \
-  --base main \
+  --base <default-branch> \
   --head [current-branch]
 ```
 
@@ -154,7 +162,7 @@ pnpm lint
 ### Next Steps
 1. Request review from team
 2. Address feedback
-3. Merge when approved
+3. Merge only after approval and successful checks
 
 ### Commands
 - View: `gh pr view`
@@ -168,7 +176,9 @@ pnpm lint
 - ✅ ALWAYS include testing info
 - ✅ ALWAYS run checks before PR
 - ✅ ALWAYS self-review first
+- ✅ ALWAYS confirm the repo/user explicitly wants PR flow before creating one
 - ❌ NEVER create PR with failing tests
+- ❌ NEVER run `/pr` from the shared default branch
 - ❌ NEVER skip description
 
 Now gathering info for PR...

package/command/ship.md

@@ -1,5 +1,5 @@
 ---
-description: Finalize work — commit, create PR, and clean up. Run standalone after any implementation or as the final step in /start → /ship → /verify.
+description: Finalize work — commit, sync, and land verified shared-checkout changes on the repo default branch. Run standalone after any implementation or as the final step in /start → /verify → /ship.
 agent: build
 ---
 
@@ -7,9 +7,9 @@ You are the **Build Agent**. Execute the `/ship` command.
 
 ## Your Task
 
-Close and ship completed work. Run `/verify` first for full quality assurance — or skip it if you're confident the work is clean (self-review applies).
+Close and ship completed work. Run `/verify` first for full quality assurance — or skip it only for quick/obvious fixes when self-review is sufficient.
 
-**Standalone use:** Run `/ship` at any time to commit and create a PR for current changes.
+**Standalone use:** Run `/ship` at any time to commit and land current shared-checkout changes.
 **In workflow:** After `/start` finishes all packets, run `/verify` then `/ship`.
 
 ## Process
@@ -28,15 +28,15 @@ Run `/verify` for full quality assurance before shipping.
 
 - Ensure active packets are verified and closed in Beads
 
-### 2. Final Self-Review
+### 3. Final Self-Review
 
-Before creating PR:
+Before landing changes:
 - Review changed files (`git diff --name-only` and `git diff`)
 - Confirm acceptance criteria from spec/plan are satisfied
 - Confirm no debug artifacts (`console.log`, `TODO`, temporary hacks)
 - Confirm changes stay within planned file impact
 
-### 3. Git Preparation
+### 4. Git Preparation
 
 ```bash
 # Ensure clean understanding of local state
@@ -49,18 +49,23 @@ git add <explicit-file-list>
 git commit -m "type(scope): description"
 ```
 
-### 4. Create PR
+### 5. Land on the shared default branch
 
-Use `/pr` flow:
-- Generate complete PR description
-- Link spec, plan, verify, and review artifacts
-- Create PR via `gh pr create`
+```bash
+# Rebase local commit(s) onto the latest shared branch state
+git pull --rebase
+
+# Publish the landed change
+git push
+```
+
+If your repo or user explicitly requires PR-based review, stop here and use `/pr` as an exception flow from a non-default branch.
 
-### 5. Post-Ship Cleanup
+### 6. Post-Ship Cleanup
 
 - Update bead/task status
 - Create handoff note if needed
-- Report PR URL + final ship summary to user
+- Report commit/branch summary to user
 
 ## Ship Checklist
 
@@ -72,7 +77,7 @@ Execution State:
 - [ ] Active packets verified
 - [ ] Beads task state updated
 
-Pre-PR:
+Pre-Ship:
 - [ ] Self-review completed
 - [ ] Acceptance criteria verified
 - [ ] No debug/temporary code
@@ -80,11 +85,12 @@ Pre-PR:
 Ship:
 - [ ] Relevant files staged explicitly
 - [ ] Commit created
-- [ ] PR created with linked artifacts
+- [ ] Rebased onto latest shared branch state
+- [ ] Changes pushed
 
 Post-Ship:
 - [ ] Status updated
-- [ ] PR URL reported
+- [ ] Final landing summary reported
 ```
 
 ## Rules
@@ -92,7 +98,9 @@ Post-Ship:
 - ✅ ALWAYS stage explicit files only
 - ✅ ALWAYS do self-review before shipping
 - ✅ STRONGLY RECOMMENDED: run `/verify` before `/ship` for non-trivial changes
+- ✅ Use `/pr` only when the user or repo policy explicitly requires a PR workflow
 - ❌ NEVER ship with known failing gates
 - ❌ NEVER use `git add -A` or `git add .`
+- ❌ NEVER create a PR or task branch as part of the default shared-workspace ship flow
 
 Now, closing completed work...

package/command/status.md

@@ -95,7 +95,7 @@ Look for:
 | Start new feature | `/create` |
 | Begin implementing | `/start` |
 | Resume paused work | `/resume` |
-| Ship & merge | `/ship` |
+| Ship & land | `/ship` |
 | Commit changes | `/commit` |
 
 ---