@preapexis/pi-kit 1.0.0

package/prompts/plan.md

@@ -0,0 +1,142 @@
+# Create Plan with Batch Model Guidance
+
+This prompt is read-only. Do not edit, create, or delete any file.
+
+## User request
+
+Use the user's message after `/plan` as the request.
+
+If no request is provided, ask the user what they want to plan.
+
+## Model preference
+
+If the user provides specific models, use those models in the recommendation.
+
+If the project has an `AGENTS.md` file, read it and check whether it contains model preferences, available models, coding rules, or execution guidance.
+
+If no model preference is provided, use Claude-style defaults:
+
+- Use Haiku for simple, repetitive, low-risk, or mechanical batches.
+- Use Sonnet for normal implementation, debugging, refactoring, and medium-complexity work.
+- Use Opus for high-risk, architecture-heavy, security-sensitive, or difficult reasoning work.
+
+## Effort levels
+
+For each batch, recommend an effort level:
+
+- Low effort: simple, obvious, low-risk changes.
+- Medium effort: normal coding work, moderate reasoning, some project context needed.
+- High effort: complex reasoning, architecture decisions, risky changes, security-sensitive work, or unclear requirements.
+
+## Your task
+
+Read the current project to understand context. Then produce a structured implementation plan based on the user request.
+
+Break the plan into batches or sub-plans. Each batch should be small enough to run safely as a separate agent task.
+
+For every batch, include:
+
+- Goal
+- Files likely involved
+- What should be done
+- Risk level
+- Recommended model
+- Recommended effort level
+- Whether user approval is needed before implementation
+
+## Rules
+
+- Read only.
+- Do not write, edit, delete, install packages, or run commands that change files.
+- Ask questions if the request is unclear.
+- Do not guess important missing details.
+- Keep the plan actionable and specific.
+- Use plain language, but include technical details where they matter.
+- Mention risks and open questions clearly.
+- Prefer smaller batches over one large implementation.
+- Put risky or unclear work in a separate batch.
+- Put tests and verification in their own batch if the work is large.
+- Recommend cheaper/faster models for simple batches and stronger models for difficult batches.
+
+## Output format
+
+```markdown
+# Plan: <short title>
+
+## Goal
+
+One sentence describing the outcome.
+
+## Context
+
+What you learned from reading the project.
+
+## Assumptions
+
+- <assumption 1>
+- <assumption 2>
+
+## Batches
+
+### Batch 1: <name>
+
+- **Goal:** <what this batch achieves>
+- **Files likely involved:**
+  - `path/to/file`
+- **Work:**
+  1. <step 1>
+  2. <step 2>
+- **Risk:** Low / Medium / High
+- **Recommended model:** Haiku / Sonnet / Opus / user-provided model
+- **Recommended effort:** Low / Medium / High
+- **Needs approval before implementation:** Yes / No
+- **Why this model:** <short reason>
+
+### Batch 2: <name>
+
+- **Goal:** <what this batch achieves>
+- **Files likely involved:**
+  - `path/to/file`
+- **Work:**
+  1. <step 1>
+  2. <step 2>
+- **Risk:** Low / Medium / High
+- **Recommended model:** Haiku / Sonnet / Opus / user-provided model
+- **Recommended effort:** Low / Medium / High
+- **Needs approval before implementation:** Yes / No
+- **Why this model:** <short reason>
+
+## Files to change
+
+- `path/to/file`
+
+## Risks or open questions
+
+- <risk 1>
+- <risk 2>
+
+## Success criteria
+
+- <criteria 1>
+- <criteria 2>
+
+## Final execution summary
+
+| Batch | Purpose   | Model  | Effort | Risk   | Approval needed |
+| ----- | --------- | ------ | ------ | ------ | --------------- |
+| 1     | <purpose> | Haiku  | Low    | Low    | No              |
+| 2     | <purpose> | Sonnet | Medium | Medium | No              |
+| 3     | <purpose> | Opus   | High   | High   | Yes             |
+
+## Recommended run order
+
+1. Run Batch <number> with <model> using <effort> effort.
+2. Run Batch <number> with <model> using <effort> effort.
+3. Run Batch <number> with <model> using <effort> effort.
+
+## Simple recommendation
+
+Use `<model>` with `<effort>` effort for batches `<batch numbers>`.
+Use `<model>` with `<effort>` effort for batches `<batch numbers>`.
+Use `<model>` with `<effort>` effort for batches `<batch numbers>`.
+```

package/prompts/review-safe.md

@@ -0,0 +1,78 @@
+# Safe Project Review
+
+Review the project safely. Do not edit, create, delete, or modify any files.
+
+## Goal
+
+Find practical issues in the current project without making changes.
+
+## Review areas
+
+Look for:
+
+- Bugs
+- Broken or suspicious logic
+- Security risks
+- Secrets in code
+- Risky shell commands
+- Risky package or dependency changes
+- Files that should not be changed
+- Missing tests
+- Missing error handling
+- Type or lint problems
+- Confusing project structure
+- Outdated or duplicated code
+
+## Steps
+
+1. First explain your review plan.
+2. Read the most relevant project files.
+3. Inspect tests and configuration if available.
+4. Report findings clearly.
+5. Do not fix anything unless the user asks.
+
+## Rules
+
+- Read only.
+- Do not edit files.
+- Do not install packages.
+- Do not run destructive commands.
+- Do not report guesses as facts.
+- If you are unsure, mark it as a question.
+- Focus on real issues with evidence.
+- Prefer important findings over long generic advice.
+
+## Output format
+
+```markdown
+# Safe Review Report
+
+## Review Plan
+
+Briefly explain what you checked.
+
+## Findings
+
+### <severity>: <title>
+
+- **File:** `path/to/file`
+- **Issue:** What looks wrong.
+- **Why it matters:** Impact or risk.
+- **Suggested fix:** What should be changed.
+
+## Missing Tests
+
+List important missing tests, if any.
+
+## Files to Treat Carefully
+
+List files or folders the agent should avoid changing casually.
+
+## Open Questions
+
+List anything unclear.
+
+## Summary
+
+Short final summary.
+```

package/prompts/save-plan.md

@@ -0,0 +1,65 @@
+# Save Plan as Markdown
+
+Save the plan below as a markdown file.
+
+## Plan to save
+
+{PLAN_CONTENT}
+
+## Your task
+
+1. Read the project root.
+2. Check whether a `docs/` folder exists.
+3. Create `docs/plans/` if needed.
+4. Save the plan as:
+
+```txt
+docs/plans/YYYY-MM-DD-plan-name.md
+```
+
+5. If `AGENTS.md` exists, ask before adding a reference to it.
+
+## File naming
+
+Pick a short slug from the plan title.
+
+Use today's date in the filename.
+
+Example:
+
+```txt
+docs/plans/2026-06-25-add-login-flow.md
+```
+
+## Output structure for the plan file
+
+```markdown
+# <plan title>
+
+## Goal
+
+## Context
+
+## Assumptions
+
+## Batches
+
+## Files to change
+
+## Risks or open questions
+
+## Success criteria
+
+## Final execution summary
+
+## Recommended run order
+```
+
+## Rules
+
+- Do not change the meaning of the plan.
+- Fix formatting only.
+- Create missing folders if needed.
+- Do not edit `AGENTS.md` unless the user approves.
+- If a plan file with the same name already exists, ask before overwriting.
+- At the end, report the saved file path.

package/prompts/security.md

@@ -0,0 +1,100 @@
+# Security Review
+
+Review the project for security issues. Do not edit any files.
+
+## Goal
+
+Find real security risks in the project with clear evidence.
+
+## Focus areas
+
+Check for:
+
+- Secret leakage
+- Hardcoded API keys or tokens
+- Unsafe shell commands
+- Command injection
+- SQL injection
+- XSS or HTML injection
+- Auth or permission bugs
+- Insecure dependencies
+- Unsafe file handling
+- Logging sensitive data
+- Missing input validation
+- Weak error handling
+- Unsafe use of `eval`, dynamic imports, or script execution
+- Dangerous deployment or CI/CD configuration
+
+## How to review
+
+1. Read the relevant files and changes.
+2. Check configuration, scripts, API routes, auth code, and file handling code.
+3. Look for hardcoded secrets, unsafe command usage, weak validation, and risky permissions.
+4. If package/security commands are available, suggest them, but do not run install or destructive commands.
+5. Report only issues with evidence.
+6. If unsure, report it under **Questions**, not as a confirmed finding.
+
+## Output format
+
+```markdown
+# Security Review Report
+
+## Summary
+
+Briefly summarize the overall security state.
+
+## Findings
+
+### <severity>: <title>
+
+- **File:** `path/to/file`
+- **Line:** `<line number or range if available>`
+- **Issue:** Short description of the problem.
+- **Evidence:** What code or behavior shows the issue.
+- **Risk:** What could go wrong.
+- **Fix:** Recommended change.
+
+## Questions
+
+List anything suspicious but not confirmed.
+
+## Suggested Checks
+
+List safe commands the user can run, for example:
+
+- `npm audit`
+- `npm run lint`
+- `npm test`
+
+Do not run risky commands without approval.
+
+## Final Notes
+
+Short closing summary.
+```
+
+## Severity levels
+
+Use:
+
+- `Critical`
+- `High`
+- `Medium`
+- `Low`
+
+If no issues are found, say:
+
+```txt
+No obvious security issues found.
+```
+
+## Rules
+
+- Read only.
+- Do not edit files.
+- Do not install packages.
+- Do not run destructive commands.
+- Be specific.
+- Include file paths and line numbers when possible.
+- Do not report theoretical issues without evidence.
+- Do not read `.env` or secret files.

package/settings.json

@@ -0,0 +1,4 @@
+{
+  "theme": "neon-guardian",
+  "defaultProjectTrust": "ask"
+}

package/skills/component-implementation/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: component-implementation
+description: Builds or modifies frontend components using the project's existing component patterns, styling system, accessibility rules, and test conventions.
+---
+
+---
+
+# Component Implementation
+
+Use this skill when creating or modifying frontend UI components.
+
+Do not use this skill for backend-only changes, database work, deployment work, or general refactors unless they directly affect frontend components.
+
+## Before Editing
+
+Inspect existing nearby components to understand:
+
+- naming conventions
+- file layout
+- props style
+- styling approach
+- accessibility patterns
+- test style
+- story/demo pattern, if any
+
+If the component requirements are unclear, ask questions before editing.
+
+## Component Rules
+
+- Prefer small, focused components.
+- Keep props clear and typed.
+- Avoid unnecessary state.
+- Prefer controlled inputs when the project already uses them.
+- Reuse existing design-system components.
+- Reuse existing icons, spacing, colors, and typography tokens.
+- Do not add a new UI package unless explicitly asked.
+- Avoid large rewrites of existing components.
+- Match the project's existing component style.
+
+## Accessibility Rules
+
+Check:
+
+- semantic HTML
+- keyboard navigation
+- visible focus states
+- labels for inputs
+- button vs link usage
+- alt text for meaningful images
+- ARIA only when necessary
+- color contrast risks
+
+## State Rules
+
+- Keep local UI state local.
+- Do not introduce global state unless needed.
+- Avoid duplicating server state in local state.
+- Preserve existing loading, error, and empty states.
+
+## After Editing
+
+Run the narrowest relevant command if available:
+
+- component test
+- unit test
+- typecheck
+- lint
+- storybook check
+
+If checks are not available or cannot run, explain why.
+
+## Output
+
+Explain:
+
+1. What component changed
+2. Why the approach matches existing patterns
+3. Accessibility considerations
+4. Tests or checks run
+5. Any remaining risks

package/skills/frontend-onboarding/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: frontend-onboarding
+description: Understands the frontend app structure, framework, routing, build tools, styling system, and test setup. Use when starting work in an unfamiliar frontend repo or feature area.
+---
+
+---
+
+# Frontend Onboarding
+
+Use this skill before making frontend changes in an unfamiliar codebase.
+
+This skill is read-only. Do not edit files during onboarding unless explicitly asked.
+
+## Inspect First
+
+Read the most relevant files:
+
+- README.md
+- AGENTS.md
+- package.json
+- vite.config._ / next.config._ / webpack.config._ / astro.config._ / svelte.config.\*
+- tsconfig.json
+- eslint.config._ / .eslintrc._
+- prettier config
+- tailwind.config.\* / theme files / design-system files
+- src/ or app/
+- routes/pages directory
+- components directory
+- tests directory
+- storybook config, if present
+
+## Identify
+
+Find and summarize:
+
+1. Frontend framework
+2. Routing approach
+3. State management approach
+4. Styling approach
+5. Component organization
+6. API/data fetching pattern
+7. Form handling pattern
+8. Test setup
+9. Build/lint/typecheck commands
+10. Important files that should be edited carefully
+
+## Safety Rules
+
+- Do not change global styles.
+- Do not introduce new UI libraries.
+- Do not change routing, auth, or data-fetching behavior casually.
+- Do not edit generated files or build output.
+- Prefer existing patterns over new abstractions.
+- If the frontend structure is unclear, ask questions before suggesting changes.
+
+## Output
+
+Return:
+
+# Frontend Summary
+
+# App Structure
+
+# Styling System
+
+# State and Data Flow
+
+# Forms and Validation
+
+# Test Commands
+
+# Risks and Careful Areas
+
+# Suggested Frontend Agent Rules
+
+# Open Questions

package/skills/frontend-quality/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: frontend-quality
+description: Reviews frontend code for accessibility, responsiveness, performance, UX states, browser behavior, and maintainability.
+---
+
+---
+
+# Frontend Quality Review
+
+Use this skill when reviewing or improving frontend quality.
+
+Do not edit files unless explicitly asked.
+
+## Review Areas
+
+Check for:
+
+- broken UI states
+- missing loading states
+- missing error states
+- missing empty states
+- poor responsive behavior
+- keyboard accessibility issues
+- focus management issues
+- incorrect semantic HTML
+- unnecessary re-renders
+- expensive rendering logic
+- unstable keys in lists
+- hydration issues
+- client/server boundary mistakes
+- inconsistent styling
+- duplicated UI logic
+- missing tests
+
+## Accessibility Checklist
+
+Verify:
+
+- interactive elements are keyboard reachable
+- form fields have labels
+- modals/dialogs manage focus correctly
+- buttons are buttons and links are links
+- images have appropriate alt text
+- errors are announced or clearly visible
+- focus states are not removed
+- ARIA is not used incorrectly
+
+## Performance Checklist
+
+Look for:
+
+- large unnecessary client bundles
+- avoidable client components
+- repeated expensive computations
+- unnecessary effects
+- unnecessary global state
+- unoptimized images
+- layout shift risks
+- over-fetching data
+
+## Rules
+
+- Prefer specific findings with file paths.
+- Do not report generic advice as a finding.
+- If unsure, mark it as a question.
+- Prioritize user-visible issues first.
+- Suggest safe, small follow-up fixes.
+
+## Output
+
+Return:
+
+# Critical Issues
+
+# Recommended Fixes
+
+# Accessibility Notes
+
+# Performance Notes
+
+# Tests to Add
+
+# Safe Follow-Up Changes
+
+# Open Questions

package/skills/safe-coding/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: safe-coding
+description: Applies safe, reviewable coding practices when modifying any file. Enforces small diffs, pre-read, no secrets, no lockfiles, and post-edit verification.
+---
+
+---
+
+# Safe Coding
+
+Use this skill when modifying code.
+
+## Before Editing
+
+- Read the file or files you plan to change before making edits.
+- Understand the existing patterns, naming conventions, and structure.
+- Identify related files that may be affected by the change.
+- If the task is unclear, ask questions before editing.
+
+## Rules
+
+- Make small, focused, reviewable changes.
+- Preserve existing behavior unless explicitly asked to change it.
+- Do not edit secrets, env files, lockfiles, build output, coverage reports, or `.git` internals.
+- Prefer targeted edits over full rewrites.
+- Do not install packages, delete files, or rewrite history without clear user approval.
+- Prefer additive changes; avoid destructive updates.
+- Explain risky or irreversible operations before executing them.
+- Match the project’s existing style and conventions.
+
+## After Editing
+
+Run the narrowest relevant verification command if available:
+
+- unit or component test
+- typecheck
+- lint
+- integration test, if applicable
+
+If verification cannot be run, explain why.
+
+## Output
+
+Explain:
+
+1. What changed and why
+2. How existing behavior is preserved
+3. Any risks or follow-up actions needed
+4. Verification command run and its result