@lovehlmmm/primekit 1.0.0

package/skills/team/references/agent-teams-controls-and-modes.md

@@ -0,0 +1,53 @@
+# Agent Teams: Runtime Controls
+
+> Canonical live source: <https://code.claude.com/docs/en/agent-teams>
+
+Controls are runtime-owned. Before a team run, inspect the active capability
+schemas and current documentation. Do not cache model lists, configuration
+keys, terminal support, UI shortcuts, storage paths, or cleanup commands here.
+
+## Control Resolution
+
+Map the workflow's semantic needs to the live runtime:
+
+- create and clean up a team
+- create, assign, read, update, and list shared work
+- spawn, message, wait for, interrupt, and shut down teammates
+- approve or reject a plan when a plan gate is requested
+- select isolation, permissions, model routing, and display mode when supported
+
+If a required capability is absent or fails, report the observed error and stop
+the team workflow. Do not silently substitute ordinary subagents or prescribe a
+cached environment change.
+
+## Plan Approval
+
+When plan approval is requested:
+
+1. Keep the teammate read-only while it plans.
+2. Require the plan to include scope, ownership, validation, and risks.
+3. Approve only through the live approval capability.
+4. On rejection, return concrete feedback and keep implementation blocked.
+5. Begin writes only after approval is confirmed.
+
+## Delegate Mode
+
+Delegate mode is a behavioral contract even when the runtime exposes a UI
+control for it. The lead coordinates, assigns, monitors, integrates reports,
+and communicates with the user. It does not edit code, run implementation
+commands, or perform the merge; those actions belong to assigned teammates.
+
+## Isolation
+
+Use separate worktrees or the runtime's equivalent isolation for concurrent
+implementation. Assign non-overlapping ownership even when isolation exists.
+Read-only research and review normally do not need worktree isolation.
+
+## Monitoring and Cleanup
+
+- Act on verified shared task state and direct teammate messages.
+- Contact a stale owner before reassigning work.
+- Replace a failed teammate without widening its file ownership.
+- Verify integrated changes and tests before shutdown.
+- Shut down all teammates, then invoke the live cleanup capability.
+- If cleanup fails, follow live recovery guidance; never remove guessed state.

package/skills/team/references/agent-teams-examples-and-best-practices.md

@@ -0,0 +1,145 @@
+# Agent Teams: Portable Examples and Practices
+
+> Canonical live source: <https://code.claude.com/docs/en/agent-teams>
+
+These examples describe collaboration semantics, not host operation names or
+parameter schemas. Discover the live team, work, delegation, message, wait,
+shutdown, and cleanup surfaces before execution.
+
+## Parallel Code Review
+
+Create three independent read-only scopes:
+
+- security and trust boundaries;
+- performance and resource behavior; and
+- test coverage and failure paths.
+
+Assign one owner and report destination per scope. Wait for all required
+reports, then deduplicate findings and reconcile disagreements before
+synthesis.
+
+## Competing-Hypothesis Investigation
+
+Give each debugger a distinct, testable theory with predicted evidence. Require
+evidence for and against the theory. Encourage direct messages that challenge
+other hypotheses. The lead waits for the relevant evidence and records why the
+surviving theory fits better than the rejected alternatives.
+
+## Parallel Feature Implementation
+
+Split the feature by non-overlapping file ownership, for example:
+
+- API and model files;
+- UI and page files; and
+- integration tests after both implementation scopes complete.
+
+Represent the tester's prerequisites in shared work state. Use isolated
+worktrees or the live runtime's equivalent for concurrent writers. Integrate
+only after implementation scopes are verified complete.
+
+## Parallel Research
+
+Use distinct questions rather than duplicate searches. Each researcher writes
+a durable report with sources, findings, trade-offs, and unanswered questions.
+The lead compares evidence quality before recommending a direction.
+
+## Give Enough Context
+
+Teammates do not inherit the lead's full conversation. Include:
+
+- exact outcome and acceptance criteria;
+- bounded files or read-only scope;
+- relevant project constraints;
+- work, plan, and report locations;
+- dependencies and ownership; and
+- expected completion and blocked handoffs.
+
+Avoid sending unrelated session history.
+
+## Size Work Correctly
+
+- Too small: coordination costs more than the work.
+- Too large: the owner runs too long without useful checkpoints.
+- Right-sized: one owner, one clear deliverable, explicit acceptance criteria,
+  and a bounded verification path.
+
+Use ordinary subagents for short or sequential work.
+
+## Protect File Ownership
+
+- Assign distinct file globs before spawning implementation teammates.
+- Give testers ownership of test files only unless the plan says otherwise.
+- If two teammates need the same file, restructure ownership or isolate and
+  integrate deliberately.
+- Never assume isolation removes merge risk.
+
+## Coordinate Through Live Capabilities
+
+- Discover the live shared-work, message, and wait surfaces.
+- Record active, completed, and blocked state as work changes.
+- Send concise completion or blocked messages with actionable evidence.
+- Wait through the live surface and re-inspect shared state after relevant
+  updates or a bounded interval appropriate to the task.
+- Treat idle as waiting, not completion.
+- Contact a stale owner before reassignment.
+
+Do not copy a monitoring command or fixed polling interval into workflow
+guidance.
+
+## Verify Before Integration
+
+A completion message is a handoff, not proof. The lead must inspect reports or
+changes, confirm prerequisite state, and run integrated verification before
+claiming success or shutting down the team.
+
+## Message Discipline
+
+- Use direct messages for scoped questions, corrections, and handoffs.
+- Use team-wide messages only for issues that affect every teammate.
+- Include the decision or evidence needed next; avoid status-only chatter.
+- Refer to teammates by the live roster's stable names.
+
+## Plan Approval
+
+When plan approval is enabled, keep the teammate read-only until the lead has
+reviewed its scope, ownership, validation, and risks through the live approval
+surface. A rejection should include concrete revision requests.
+
+## Shutdown and Cleanup
+
+1. Confirm required work is complete or has a durable blocked handoff.
+2. Request graceful shutdown through the live surface.
+3. Wait for acknowledgement or a documented refusal.
+4. Shut down every teammate before team cleanup.
+5. If cleanup fails, report the observed error and follow current runtime
+   guidance. Never remove guessed storage or configuration paths.
+
+## Recovery Patterns
+
+### Required Capability Missing
+
+Stop the team workflow and report the capability or configuration error that
+the live runtime returned. Do not prescribe a remembered enablement flag,
+client restriction, or environment setting.
+
+### Teammate Appears Stalled
+
+Inspect shared work and messages, contact the owner, and wait for a bounded
+response. If replacement is necessary, preserve the handoff and assign the
+same scope without widening ownership.
+
+### Shared State Is Stale
+
+Ask the owner to reconcile its actual progress, then verify the underlying
+artifact. Do not synthesize or release dependent work from an idle signal.
+
+### Integration Conflicts
+
+Stop parallel integration, preserve both branches, and assign one owner to
+resolve the conflict against the accepted plan. Re-run integrated verification.
+
+## Live Facts, Not Documentation Snapshots
+
+Resolve current availability, models, permissions, display modes, limits,
+resume behavior, memory, client support, and storage through the live runtime
+or canonical source. They are intentionally absent from this reference.

package/skills/team/references/agent-teams-official-docs.md

@@ -0,0 +1,67 @@
+# Agent Teams: Stable Operating Model
+
+> Canonical live source: <https://code.claude.com/docs/en/agent-teams>
+
+This reference records the durable model used by `pk:team`. It deliberately
+does not copy current flags, tool schemas, model choices, storage paths,
+shortcuts, client support, limits, or experimental status. Inspect those from
+the live runtime and canonical documentation at execution time.
+
+## Purpose
+
+Agent Teams coordinate independent teammate sessions through a lead, shared
+work state, and direct messages. Use them when parallel workers need separate
+context and must coordinate. Use ordinary subagents for focused work that only
+needs to return a result to its parent.
+
+Good team work has independent boundaries:
+
+- research from different angles
+- implementation across non-overlapping files or isolated worktrees
+- review from distinct specialties
+- debugging with competing hypotheses
+
+Avoid teams for sequential work, same-file editing, or tasks whose coordination
+cost exceeds their parallel value.
+
+## Runtime Boundary
+
+Before creating a team:
+
+1. Inspect the live team, task, delegation, message, shutdown, and cleanup
+   capabilities and their schemas.
+2. Inspect current model, permission, isolation, display, and capacity controls
+   only when the task needs them.
+3. Create the team through the live capability.
+4. If creation is unavailable or fails, stop and report the observed error.
+   Do not guess an enablement flag, supported client, or state directory.
+
+The executable operation sequence belongs to `../SKILL.md`. This reference
+must not become a second tool-schema authority.
+
+## Stable Invariants
+
+- The lead owns decomposition, non-overlapping file ownership, task state,
+  integration, and the final answer.
+- Each teammate receives explicit scope, acceptance criteria, work context,
+  report path, and project rules.
+- Implementation workers use isolation when concurrent edits could conflict.
+- Teammates report actionable results and mark their shared work state.
+- The lead verifies results and runs integrated tests; a teammate's completion
+  message is not verification.
+- Shutdown every teammate before cleanup.
+- If cleanup fails, use the live runtime recovery guidance; never delete a
+  guessed directory.
+
+## Live Facts to Resolve, Not Cache
+
+Consult the active runtime or canonical source for:
+
+- capability and parameter names
+- enablement and availability
+- model routing and mixed-model support
+- permissions and inheritance
+- display modes, clients, terminals, and shortcuts
+- concurrency and cost limits
+- task and hook event schemas
+- session, memory, storage, resume, and cleanup behavior

package/skills/team/references/team-coordination-rules.md

@@ -0,0 +1,92 @@
+# Team Coordination Rules
+
+> These rules only apply when operating as a teammate within an Agent Team.
+> They live inside the `pk:team` skill so normal sessions do not load team-only coordination context.
+
+Rules for agents operating as teammates within an Agent Team.
+
+## File Ownership (CRITICAL)
+
+- Each teammate MUST own distinct files — no overlapping edits
+- Define ownership via glob patterns in task descriptions: `File ownership: src/api/*, src/models/*`
+- Lead resolves ownership conflicts by restructuring tasks or handling shared files directly
+- Tester owns test files only; reads implementation files but never edits them
+- If ownership violation detected: STOP and report to lead immediately
+
+## Git Safety
+
+- Prefer git worktrees for implementation teams — each dev in own worktree eliminates conflicts
+- Never force-push from a teammate session
+- Commit frequently with descriptive messages
+- Pull before push to catch merge conflicts early
+- If working in a git worktree, commit/push to the worktree branch — not main or dev
+
+## Communication Protocol
+
+- Discover the live message surface before communicating
+- Use direct messages for scoped questions and handoffs; identify recipients by live roster name
+- Use team-wide messages only for critical issues affecting the entire team
+- Reconcile shared work state before sending a completion message to the lead
+- Include actionable findings in messages, not just "I'm done"
+- Never send structured JSON status messages — use plain text
+
+## PrimeKit Stack Conventions
+
+### Report Output
+- Save reports to `{CK_REPORTS_PATH}` (injected via hook, fallback: `plans/reports/`)
+- Naming: `{type}-{date}-{slug}.md` where type = your role (researcher, reviewer, debugger)
+- Sacrifice grammar for concision. List unresolved questions at end.
+
+### Commit Messages
+- Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
+- No AI authorship attribution in commit messages; product/runtime names are valid
+- Keep commits focused on actual code changes
+
+### Docs Sync (Implementation Teams Only)
+- After completing implementation tasks, lead MUST evaluate docs impact
+- State explicitly: `Docs impact: [none|minor|major]`
+- If impact: update `docs/` directory or note in completion message
+
+## Task Claiming
+
+- Discover the live shared-work surface and claim the assigned or next unblocked item
+- Record ownership and active state before starting
+- After completion, inspect shared state for newly unblocked work
+- If all tasks blocked, notify lead and offer to help unblock
+
+## Plan Approval Flow
+
+When plan approval is required:
+1. Research and plan your approach (read-only — no file edits)
+2. Submit the plan through the discovered approval surface
+3. Wait for the lead's response
+4. If rejected: revise based on feedback, resubmit
+5. If approved: proceed with implementation
+
+## Conflict Resolution
+
+- If two teammates need the same file: escalate to lead immediately
+- If a teammate's plan is rejected twice: lead takes over that task
+- If findings conflict between reviewers: lead synthesizes and documents disagreement
+- If blocked by another teammate's incomplete work: message them directly first, escalate to lead if unresponsive
+
+## Shutdown Protocol
+
+- Approve shutdown requests unless mid-critical-operation
+- Mark current task completed before approving shutdown only when the assigned work is actually complete
+- If work is incomplete, leave status unchanged or mark blocked with a concise handoff before approving or rejecting shutdown
+- If rejecting shutdown, explain why concisely
+- Respond to the original request through the live shutdown surface
+
+## Idle State (Normal Behavior)
+
+- Going idle after sending a message is NORMAL — not an error
+- Idle means waiting for input, not disconnected
+- Sending a message to an idle teammate wakes them up
+- Do not treat idle notifications as completion signals — check task status instead
+
+## Discovery
+
+- Discover teammates from the live team roster
+- Always refer to teammates by NAME (not agent ID)
+- Use roster names consistently for messages and work ownership

package/skills/tech-graph/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 fireworks-tech-graph contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.