@lovehlmmm/primekit 1.0.0

package/skills/plan/references/archive-workflow.md

@@ -0,0 +1,81 @@
+# Archive Workflow
+
+## Your mission
+Read and analyze the plans, then write journal entries and archive specific plans or all plans in the `plans` directory.
+
+## Plan Resolution
+1. If `$ARGUMENTS` provided → Use that path
+2. Else read all plans in the `plans` directory
+
+## Workflow
+
+### Step 1: Read Plan Files
+
+Read the plan directory:
+- `plan.md` - Overview and phases list
+- `phase-*.md` - 20 first lines of each phase file to understand the progress and status
+
+### Step 2: Summarize the plans and document them with `/pk:journal` skill invocation
+
+Respect the shared "Journal step — opt-out" contract before prompting. Skip the
+entire journal sub-step silently — do NOT ask — when either applies:
+- The invocation includes the `--skip-journal` flag, OR
+- `primekit config prefs resolve --json | jq -r 'if .prefs.journal.auto == false then "false" else "true" end'` returns `false`. If the command errors or prints anything other than the exact string `false`, treat as `true` (default) — corrupt or missing config never suppresses the automatic journal.
+
+Precedence: flag > project config > user config > default (`true`). When
+skipped, print one line and jump to Step 3:
+- `journal skipped by --skip-journal` (flag), or
+- `journal skipped by preference` (config).
+
+Otherwise, use `ask_user capability` tool to ask if user wants to document journal entries or not.
+Skip this step if user selects "No".
+If user selects "Yes":
+- Analyze the information in previous steps.
+- Use delegate_agent capability with `subagent_type="journal-writer"` in parallel to document all plans.
+- Journal entries should be concise and focused on the most important events, key changes, impacts, and decisions.
+- Keep journal entries in the `./plans/journals/` directory.
+- Treat journals as chronological work records; move durable rules to current
+  docs or ADRs.
+
+### Step 3: Ask user to confirm the action before archiving these plans
+Use `ask_user capability` tool to ask if user wants to proceed with archiving these plans, select specific plans to archive or all completed plans only.
+
+Archiving is an **index-visibility change, not file deletion**. The plan `.md`
+files are canonical repo history and stay on disk. Do NOT offer, and never run, a
+`rm -rf`/permanent-delete of a plan folder — that discards versioned history and
+is exactly the "stale plan read as false context" harm this workflow avoids.
+
+### Step 4: Archive the plans
+Archive by changing index visibility, never by touching files:
+- Run `primekit plan archive <plan-dir>` (and/or `primekit plan cleanup` for a retention
+  sweep of stale closed plans — dry-run by default). Run `primekit plan --help` and
+  each subcommand's `--help` for exact flags; those live surfaces own syntax.
+- These mark the plan closed/archived in the rebuildable index. They do NOT move
+  or delete the `plan.md`/`phase-*.md` files.
+- Physically removing a plan folder is a separate, explicit user action only,
+  and only after the plan is closed/archived in the index, journaled, and its
+  files are committed. The user runs `git rm -r ./plans/<plan-dir>` themselves —
+  `git rm` refuses untracked paths and preserves history for tracked ones, so it
+  cannot silently destroy uncommitted work. Never fall back to `rm -rf`: if
+  `plans/` is gitignored in the consuming repo, deletion is unrecoverable. Never
+  a skill default, never a broad-glob delete.
+- If `primekit` is unavailable, report the skip and leave the files untouched; do not
+  hand-move plans into an `./plans/archive` directory.
+
+### Step 5: Ask if user wants to commit the changes
+Use `ask_user capability` tool to ask if user wants to commit the changes with these options:
+- Stage and commit the changes (Use `/pk:git` for commit flow)
+- Commit and push the changes (Use `/pk:git` for push flow)
+- Nah, I'll do it later
+
+## Output
+After archiving the plans, provide summary:
+- Number of plans archived (index visibility only; files kept on disk)
+- Table of plans that are archived (title, status, created date, LOC)
+- Table of journal entries that are created (title, status, created date, LOC)
+
+## Important Notes
+- Only ask questions about genuine decision points
+- Sacrifice grammar for concision
+- List any unresolved questions at the end
+- Ensure token efficiency while maintaining high quality

package/skills/plan/references/codebase-understanding.md

@@ -0,0 +1,48 @@
+# Codebase Understanding Phase
+
+**When to skip:** If provided with scout reports, skip this phase.
+
+## Core Activities
+
+### Parallel Scout Agents
+- Use `/pk:scout ext` (preferred) or `/pk:scout` (fallback) skill invocation to search the codebase for files needed to complete the task
+- Each scout locates files needed for specific task aspects
+- Wait for all scout agents to report back before analysis
+- Efficient for finding relevant code across large codebases
+
+### Project Context Discovery
+
+Do not assume a standard documentation corpus. Discover context by role:
+
+1. Read the repository's loaded instructions and root README.
+2. Follow its documentation navigation to locate current development and security rules, architecture or source maps, product requirements, and any design-system guidance relevant to the task.
+3. Verify documented structure and behavior against current source, tests, manifests, and build configuration.
+4. If navigation is absent, incomplete, or conflicting, use targeted scouts to locate the owning evidence and record the actual paths for the planner.
+
+Documentation serves human and AI collaborators; current implementation evidence determines what is actually present.
+
+### Environment Analysis
+- Review development environment setup
+- Analyze dotenv files and configuration
+- Identify required dependencies
+- Understand build and deployment processes
+
+### Pattern Recognition
+- Study existing patterns in codebase
+- Identify conventions and architectural decisions
+- Note consistency in implementation approaches
+- Understand error handling patterns
+
+### Integration Planning
+- Identify how new features integrate with existing architecture
+- Map dependencies between components
+- Understand data flow and state management
+- Consider backward compatibility
+
+## Best Practices
+
+- Start with documentation before diving into code
+- Use scouts for targeted file discovery
+- Document patterns found for consistency
+- Note any inconsistencies or technical debt
+- Consider impact on existing features

package/skills/plan/references/output-standards.md

@@ -0,0 +1,225 @@
+# Output Standards & Quality
+
+## Plan File Format
+
+### YAML Frontmatter (Required for plan.md)
+
+All `plan.md` files MUST include YAML frontmatter at the top:
+
+```yaml
+---
+title: "{Brief plan title}"
+description: "{One-sentence summary for card preview}"
+status: pending  # pending | in-progress | completed | cancelled
+priority: P2     # P1 (High) | P2 (Medium) | P3 (Low)
+effort: 4h       # Estimated total effort
+issue: <issue-number>  # GitHub issue number (if applicable)
+branch: <owner>/feat/<feature-name>
+tags: [frontend, api]  # Category tags
+blockedBy: []    # Same-scope refs by default; use global:/project: for cross-scope
+blocks: []       # Example: [project:<timestamp>-user-dashboard]
+created: <date>
+---
+```
+
+When `--html` is active, `plan.html` is the primary artifact after validation
+and red-team gates. A companion `plan.md` may exist as a short index for
+metadata, issue links, and cook handoff compatibility only. Do not duplicate
+the full plan body in both files unless a downstream cook handoff needs
+Markdown.
+
+### HTML Plan Format (`--html`)
+
+`plan.html` must be:
+- Self-contained with inline CSS and JavaScript.
+- Responsive and keyboard-accessible.
+- Structured around overview, visible phase outlines, user flows, risks, an
+  implementation workflow diagram, annotated UI/UX mockups when UI is in scope,
+  diagrams, charts, citations, and open questions.
+- Interactive where useful: tabs, expandable sections, filters, toggles, or
+  chart controls.
+- Source-cited with visible URL citations for external docs, GitHub issues,
+  specs, and research links.
+- Safe to open directly from disk without a dev server.
+- Designed in editorial magazine style: warm paper `#faf7f2`, paper panels
+  `#f0ebe1`, ink `#0a0a0a`, muted `#6b6258`, accent red `#b8232c`, serif
+  display, mono labels, hairline dividers, asymmetric grids, rule lines, and
+  subtle paper grain.
+- Free of gradients, shadows, rounded cards, pure white backgrounds, emoji
+  icons, generic SaaS styling, and decorative bokeh/orbs.
+- Explicit on the main page: every phase shows title, status, priority,
+  dependencies, objective, 3-6 key bullets, related files, success highlights,
+  and test/validation gate when known.
+- Modal-driven for detail: every phase outline opens a keyboard-accessible
+  modal that renders full phase markdown with headings, lists, checkboxes,
+  tables, code fences, inline code, blockquotes, links, horizontal rules, and
+  frontmatter metadata.
+- Visual on implementation: include at least one implementation workflow diagram
+  (flowchart, sequence, or architecture) rendered inline; `--html` treats this
+  as required, not optional.
+- Mockup-driven when the plan touches UI/UX: embed annotated mockups of the
+  proposed screens or components inline, derived from the project design
+  guidelines (`docs/design-guidelines.md` when present, else the built-in
+  editorial contract), with callouts mapping elements to design tokens,
+  interaction states, and acceptance criteria so the user previews intended UI
+  before implementation.
+- Illustrated when image generation is available: use `imagegen`,
+  built-in `image_gen`, or `create_image` to generate 1-3 watercolor technical
+  sketch assets, keep sources under `{plan-dir}/assets/`, and embed selected
+  images as data URIs so `plan.html` remains portable.
+
+### AgentWiki Publish Format (`--wiki`)
+
+When `--wiki` is active:
+- Publish only final reviewed artifacts after validation/red-team gates.
+- Use AgentWiki CLI when `agentwiki whoami` succeeds; otherwise use AgentWiki
+  MCP document/upload/share/static-site tools when exposed.
+- Default to private/workspace sharing with `agentwiki doc share`. Use
+  `agentwiki doc publish` only when the user explicitly requests public
+  document publishing.
+- Markdown plans publish as AgentWiki documents. If details live across
+  phase files, prepare `{plan-dir}/wiki-publish.md` as a concise combined
+  document or index before upload.
+- HTML plans remain local by default. Publish through AgentWiki hosted static
+  sites using the self-contained `plan.html` only when the user explicitly
+  requests a public hosted site.
+- Record returned document, share, publish, or site URLs in the final response.
+  If `--github` is also active, add the wiki URL to the GitHub issue.
+- If AgentWiki is unavailable or unauthenticated, skip publishing without
+  failing plan creation and report the exact missing capability.
+- Redact secrets, tokens, private logs, customer data, and local-only absolute
+  paths before publishing.
+
+### Auto-Population Rules
+
+When creating plans, auto-populate these fields:
+- **title**: Extract from task description
+- **description**: First sentence of Overview section
+- **status**: Always `pending` for new plans
+- **priority**: From user request or default `P2`
+- **effort**: Sum of phase estimates
+- **issue**: Parse from branch name or context
+- **branch**: Current git branch (`git branch --show-current`)
+- **tags**: Infer from task keywords (e.g., frontend, backend, api, auth)
+- **blockedBy**: Detected during pre-creation scan (empty `[]` if none)
+- **blocks**: Detected during pre-creation scan (empty `[]` if none)
+- **created**: Today's date in YYYY-MM-DD format
+
+### Cross-Scope Reference Syntax
+
+- Bare reference: `<timestamp>-auth-system`
+  - Meaning: same scope as the current plan.
+- Global reference: `global:<timestamp>-auth-system`
+  - Meaning: resolve against the configured global plans root.
+- Project reference: `project:<timestamp>-auth-system`
+  - Meaning: resolve against the current project plans root.
+
+Missing references should warn and render as `not found`. They should not block plan creation.
+
+### Tag Vocabulary (Recommended)
+
+Use these predefined tags for consistency:
+- **Type**: `feature`, `bugfix`, `refactor`, `docs`, `infra`
+- **Domain**: `frontend`, `backend`, `database`, `api`, `auth`
+- **Scope**: `critical`, `tech-debt`, `experimental`
+
+### Runtime Work Item Guidance
+
+When a live task-management surface is available, derive concise work items
+from the plan. Use an imperative action and deliverable, include the relevant
+acceptance criteria, and retain a durable source-plan reference. Discover the
+runtime's exact fields instead of copying a parameter schema into the plan.
+
+See `task-management.md` for runtime capability discovery, durable mapping, and handoff rules.
+
+## Task Breakdown
+
+- Transform complex requirements into manageable, actionable tasks
+- Each task independently executable with clear dependencies
+- Prioritize by dependencies, risk, business value
+- Eliminate ambiguity in instructions
+- Include specific file paths for all modifications
+- Provide clear acceptance criteria per task
+
+### File Management
+
+List affected files with:
+- Full paths (not relative)
+- Action type (modify/create/delete)
+- Brief change description
+- Dependencies on other changes
+- Discover and follow the consuming repository's instruction and development-standard documents; do not assume a fixed docs path.
+
+## Workflow Process
+
+1. **Initial Analysis** → Read docs, understand context
+2. **Research Phase** → Spawn researchers in parallel, investigate approaches
+3. **Synthesis** → Analyze reports, identify optimal solution
+4. **Design Phase** → Create architecture, implementation design
+5. **Plan Documentation** → Write comprehensive plan in Markdown, or `plan.html`
+   when `--html` is present
+6. **Review & Refine** → Ensure completeness, clarity, actionability
+
+## Output Requirements
+
+### What Planners Do
+- Create plans ONLY (no implementation)
+- Provide plan file path and summary
+- With `--html`, provide the `plan.html` path first and say it is authoritative
+- With `--wiki`, provide the AgentWiki document/share/site URL when published,
+  or the exact skip reason when unavailable
+- Self-contained plans with necessary context
+- Code snippets/pseudocode when clarifying
+- Multiple options with trade-offs when appropriate
+- Discover and follow the consuming repository's instruction and development-standard documents; do not assume a fixed docs path.
+
+### Writing Style
+**IMPORTANT:** Sacrifice grammar for concision
+- Focus clarity over eloquence
+- Use bullets and lists
+- Short sentences
+- Remove unnecessary words
+- Prioritize actionable info
+
+### Unresolved Questions
+**IMPORTANT:** Use `ask_user capability` to ask users for unresolved questions at the end
+- Questions needing clarification
+- Technical decisions requiring input
+- Unknowns impacting implementation
+- Trade-offs requiring business decisions
+Revise the plan and phases based on the answers.
+
+## Quality Standards
+
+### Thoroughness
+- Thorough and specific in research/planning
+- Consider edge cases, failure modes
+- Think through entire user journey
+- Document all assumptions
+
+### Maintainability
+- Consider long-term maintainability
+- Design for future modifications
+- Document decision rationale
+- Avoid over-engineering
+- Discover and follow the consuming repository's instruction and development-standard documents; do not assume a fixed docs path.
+
+### Research Depth
+- When uncertain, research more
+- Multiple options with clear trade-offs
+- Validate against best practices
+- Consider industry standards
+
+### Security & Performance
+- Address all security concerns
+- Identify performance implications
+- Plan for scalability
+- Consider resource constraints
+
+### Implementability
+- Detailed enough for junior developers
+- Validate against existing patterns
+- Ensure codebase standards consistency
+- Provide clear examples
+
+**Remember:** Plan quality determines implementation success. Be comprehensive, consider all solution aspects.

package/skills/plan/references/plan-organization.md

@@ -0,0 +1,267 @@
+# Plan Creation & Organization
+
+## Directory Structure
+
+### Plan Location
+
+Use `Plan dir:` from `## Naming` section injected by hooks. This is the full computed path.
+
+Default scope:
+- project scope → `plans/<timestamp>-authentication/`
+- global scope → `{configured-global-plans-root}/<timestamp>-authentication/`
+  - Default when unset: `~/.claude/plans/<timestamp>-authentication/`
+
+Use global scope only when `--global` is explicit or there is no project context.
+
+### File Organization
+
+In the active scope root:
+```
+{plan-dir}/                                    # From `Plan dir:` in ## Naming
+├── research/
+│   ├── researcher-XX-report.md
+│   └── ...
+├── reports/
+│   ├── scout-report.md
+│   ├── researcher-report.md
+│   └── ...
+├── assets/                                    # Generated image sources for plan.html
+├── plan.md                                    # Overview access point
+├── plan.html                                  # Primary artifact when --html is used
+├── wiki-publish.md                            # Optional combined doc when --wiki publishes Markdown
+├── phase-01-setup-environment.md              # Setup environment
+├── phase-02-implement-database.md             # Database models
+├── phase-03-implement-api-endpoints.md        # API endpoints
+├── phase-04-implement-ui-components.md        # UI components
+├── phase-05-implement-authentication.md       # Auth & authorization
+├── phase-06-implement-profile.md              # Profile page
+└── phase-07-write-tests.md                    # Tests
+```
+
+### Task Hydration
+
+After creating plan.md and phase files, hydrate tasks (unless `--no-tasks`):
+When `--html` is present, hydrate tasks only from the companion `plan.md`
+index if it contains actionable checkboxes; otherwise skip hydration and state
+that `plan.html` is the authoritative artifact.
+1. Discover the live task-management surface
+2. If available, mirror phases, dependencies, and critical high-risk steps
+3. Otherwise, keep progress in the active plan; see `task-management.md` for the cook handoff protocol
+
+### HTML Artifact Layout
+
+When `--html` is present:
+- Keep `plan.html` as the primary user-facing artifact.
+- Keep `plan.md` as a concise index for metadata, GitHub links, and cook handoff
+  compatibility when needed.
+- Keep every `phase-*.md` as the detailed implementation contract when Markdown
+  phase files are generated.
+- Put generated image source files under `assets/`, then embed selected images
+  in `plan.html` as data URIs.
+- Verify the main page exposes every phase outline and that each outline opens
+  a rendered markdown detail modal.
+- Verify `plan.html` opens as a portable single file with no missing local asset
+  paths.
+
+### AgentWiki Publish Layout
+
+When `--wiki` is present:
+- Publish after final plan gates and after `plan.html` exists when `--html`
+  is also present.
+- Use `agentwiki doc share` for the default private/workspace document URL.
+  Run `agentwiki doc publish` only when the user explicitly requests public
+  document publishing.
+- For Markdown output, publish `plan.md` when it is complete enough to stand
+  alone. If phase details are split across files, create `wiki-publish.md` as
+  a concise combined document or index before uploading.
+- For HTML output, keep `plan.html` local by default. Upload the portable
+  `plan.html` through AgentWiki hosted static sites only when the user
+  explicitly requests a public hosted site.
+- Record returned AgentWiki document/share/site URLs in `plan.md` when a
+  companion Markdown index exists. If `--github` is active, add the URL to the
+  GitHub issue.
+- Do not publish secrets, raw logs, private env values, or local-only absolute
+  paths.
+
+### Active Plan State Tracking
+
+See SKILL.md "Active Plan State" section for full rules. Key points:
+- Check `## Plan Context` injected by hooks for active/suggested/none state
+- After creating plan: use the active plan mechanism provided by the host project or dashboard
+- Active plans use plan-specific reports path; suggested plans use default path
+
+## Plan Creation Via CLI
+
+After determining phases from research/design:
+
+1. **Read live help:** Run `primekit plan --help`, then run the selected scaffolding
+   subcommand with `--help`. Live help owns syntax and flags.
+
+2. **Scaffold via CLI:** Use the operations described by live help to create the
+   plan and required phases. Do not copy a command schema into the plan.
+
+3. **Fill content sections** in plan.md via edit-file capability:
+   - `## Overview` — brief description
+   - `## Dependencies` — cross-plan dependencies
+
+4. **Fill each phase-XX.md** with:
+   - Architecture, implementation steps, success criteria
+   - Requirements, risk assessment, security considerations
+
+5. **NEVER edit the Phases table directly** when it is CLI-owned. Use the
+   status and structure operations exposed by live help.
+
+6. **If `--html`, generate `plan.html` after final plan gates:**
+   - Re-read `plan.md` and every `phase-*.md` that exists.
+   - Extract visible phase outline summaries for the main page.
+   - Render full phase markdown into click-open detail modals.
+   - Embed generated watercolor technical sketch images when available.
+   - Verify `plan.html` opens without missing local assets.
+
+6. **If `--wiki`, publish final artifacts after gates:**
+   - Use `agentwiki doc upload` followed by `agentwiki doc share` for private
+     Markdown document sharing.
+   - Use `agentwiki doc publish` only on explicit user request for public docs.
+   - Use `agentwiki sites upload` for `plan.html` only on explicit user request
+     for a public hosted site.
+   - Use AgentWiki MCP only when equivalent document/share/site capabilities
+     are exposed in the active session.
+   - Capture and report the returned URL, or report the exact skip reason.
+
+**MANDATORY:** Markdown plan creation goes through CLI. The `primekit` CLI is required
+for PrimeKit users. If the selected scaffolding operation fails, report the error; do not fall
+back to direct Markdown file scaffolding. In `--html` mode, write the primary
+`plan.html` after planning gates finish so the HTML reflects the reviewed plan.
+If `--github` is also present, use CLI scaffolding or a concise Markdown index
+only for the requested repo-relative `plan.md` link.
+
+## File Structure
+
+### Overview Plan (plan.md)
+
+**IMPORTANT:** All plan.md files MUST include YAML frontmatter. See `output-standards.md` for schema.
+When `--html` is active, `plan.md` may be a concise index instead of the full
+plan body. It should link to `plan.html`, summarize phases, and keep GitHub
+issue metadata stable.
+
+**Example plan.md structure:**
+```markdown
+---
+title: "Feature Implementation Plan"
+description: "Add user authentication with OAuth2 support"
+status: pending
+priority: P1
+effort: 8h
+issue: <issue-number>
+branch: <owner>/feat/<feature-name>
+tags: [auth, backend, security]
+blockedBy: []
+blocks: [global:<timestamp>-user-dashboard]
+created: <date>
+---
+
+# Feature Implementation Plan
+
+## Overview
+
+Brief description of what this plan accomplishes.
+
+## Cross-Plan Dependencies
+
+| Relationship | Plan | Status |
+|-------------|------|--------|
+| Blocks | `global:<timestamp>-user-dashboard` | pending |
+
+## Phases
+
+| Phase | Name | Status |
+|-------|------|--------|
+| 1 | [Setup Environment](./phase-01-setup.md) | Pending |
+| 2 | [Core Implementation](./phase-02-impl.md) | Pending |
+| 3 | [Testing & Validation](./phase-03-test.md) | Pending |
+
+<!-- IMPORTANT: Link text MUST be human-readable names (not filenames).
+     Bad:  [phase-01-setup.md](./phase-01-setup.md)
+     Good: [Setup Environment](./phase-01-setup.md) -->
+
+## Dependencies
+
+- List key dependencies here
+```
+
+Reference rules:
+- Bare refs stay in the current scope.
+- Use `global:` or `project:` when the dependency crosses scopes.
+- The live plan CLI's status operation is authoritative for resolved dependency state; confirm its invocation through help.
+
+**Guidelines:**
+- Keep generic and under 80 lines
+- List each phase with status/progress
+- Link to detailed phase files
+- Key dependencies
+
+### Phase Files (phase-XX-name.md)
+Discover and follow the consuming repository's instruction and development-standard documents. Do not assume a fixed docs path.
+Each phase file should contain:
+
+**Context Links**
+- Links to related reports, files, documentation
+
+**Overview**
+- Priority
+- Current status
+- Brief description
+
+**Key Insights**
+- Important findings from research
+- Critical considerations
+
+**Requirements**
+- Functional requirements
+- Non-functional requirements
+
+**Architecture**
+- System design
+- Component interactions
+- Data flow
+
+**Related Code Files**
+- List of files to modify
+- List of files to create
+- List of files to delete
+
+**Implementation Steps**
+- Detailed, numbered steps
+- Specific instructions
+
+**Todo List**
+- Checkbox list for tracking
+
+**Success Criteria**
+- Definition of done
+- Validation methods
+
+**Risk Assessment**
+- Potential issues
+- Mitigation strategies
+
+**Security Considerations**
+- Auth/authorization
+- Data protection
+
+**Next Steps**
+- Dependencies
+- Follow-up tasks
+
+### Deep / TDD Extensions
+
+When `--deep` is used, add:
+- a file inventory table with action, rough size, and test impact
+- a test scenario matrix for critical, high, and medium paths
+- a dependency map that calls out links to other phases
+
+When `--tdd` is used, add:
+- a **Tests Before** section for regression coverage written first
+- a **Refactor** section describing the protected code changes
+- a **Tests After** section for new behavior introduced in that phase
+- a regression gate listing the compile/test command that must pass