@paulojalowyj/openkit 0.1.1

package/.opencode/commands/impl.md

@@ -0,0 +1,242 @@
+---
+description: Execute implementation from plan files with multi-agent coordination
+subtask: true
+---
+
+**IMPLEMENTATION MODE ACTIVATED**
+
+**User input:** $ARGUMENTS
+
+**If it starts with "from":**
+- Extract the path (e.g., "from docs/sprint/Sprint-17/TASKS.md")
+- Read that plan and execute its tasks
+
+**If $ARGUMENTS is empty or missing "from":**
+Use the question tool to ask:
+```javascript
+question({
+  questions: [{
+      question: "Which sprint should I execute?",
+      header: "Sprint Selection",
+      options: [
+        { label: "Latest Sprint", description: "Continue most recent work" },
+        { label: "Custom Path", description: "Provide full path" }
+      ]
+    }]
+})
+```
+
+**Execution Protocol:**
+
+### Phase 0: TodoList Setup (MANDATORY)
+
+Before any implementation work:
+
+1. **Read existing todolist:**
+   ```javascript
+   todoread()
+   ```
+
+2. **Check if planning todolist exists:**
+   - If exists (from `/plan`): Continue with implementation todolist
+   - If not exists: Create implementation todolist from scratch
+
+3. **Create implementation todolist:**
+   ```javascript
+   todowrite({
+     todos: [
+       {
+         id: "impl-01-precheck",
+         content: "Pre-implementation checklist validation",
+         status: "in_progress",
+         priority: "high"
+       },
+       {
+         id: "impl-02-analysis",
+         content: "Read context and identify scope",
+         status: "pending",
+         priority: "high"
+       },
+       {
+         id: "impl-03-p0-foundation",
+         content: "P0: Foundation (DB architect + Security auditor)",
+         status: "pending",
+         priority: "high"
+       },
+       {
+         id: "impl-04-p1-backend",
+         content: "P1: Core Backend (backend-specialist)",
+         status: "pending",
+         priority: "high"
+       },
+       {
+         id: "impl-05-p2-frontend",
+         content: "P2: UI/UX (frontend-specialist or mobile-developer)",
+         status: "pending",
+         priority: "high"
+       },
+       {
+         id: "impl-06-p3-polish",
+         content: "P3: Polish (test-engineer + performance-optimizer)",
+         status: "pending",
+         priority: "medium"
+       },
+       {
+         id: "impl-07-tasks-update",
+          content: "Update sprint TASKS.md with completion status",
+         status: "pending",
+         priority: "medium"
+       }
+     ]
+   })
+   ```
+
+4. **Update todolist** as you complete each phase
+
+### Pre-Implementation Checklist
+- [ ] `docs/` exists
+- [ ] Spec artifacts exist (`docs/requirements/<feature>/`)
+- [ ] Plan exists (`docs/requirements/<feature>/PLAN.md`)
+- [ ] Selected sprint defined
+- [ ] `TASKS.md` exists and is valid
+- [ ] User approval obtained
+- [ ] Execution order determined
+
+**SDD Gate (MANDATORY):**
+If any required spec or plan artifact is missing, STOP and direct the user to run `/specify`, `/clarify`, and `/plan` first.
+
+**After checklist:**
+- Update todolist: Mark "impl-01-precheck" as `completed`
+- Mark "impl-02-analysis" as `in_progress`
+
+### Execution Order (P0 → P1 → P2 → P3)
+
+**P0 - Foundation (Required if applicable):**
+-  Invoke `database-architect` (if DB is needed)
+-  Invoke `security-auditor` (always for auth/security)
+
+** STOP:**
+- Update todolist: Mark "impl-03-p0-foundation" as `completed`
+- Mark "impl-04-p1-backend" as `in_progress`
+- Use the question tool to ask "P0 phase complete. Proceed to P1 (Core Backend)?"
+
+**P1 - Core Backend:**
+-  Invoke `backend-specialist`
+
+** STOP:**
+- Update todolist: Mark "impl-04-p1-backend" as `completed`
+- Mark "impl-05-p2-frontend" as `in_progress`
+- Use the question tool to ask "P1 phase complete. Proceed to P2 (UI/UX)?"
+
+**P2 - UI/UX:**
+-  Invoke `frontend-specialist` (WEB projects)
+-  Invoke `mobile-developer` (MOBILE projects)
+
+** STOP:**
+- Update todolist: Mark "impl-05-p2-frontend" as `completed`
+- Mark "impl-06-p3-polish" as `in_progress`
+- Use the question tool to ask "P2 phase complete. Proceed to P3 (Polish)?"
+
+**P3 - Polish:**
+-  Invoke `test-engineer`
+-  Invoke `performance-optimizer` (if needed)
+
+**After P3:**
+- Update todolist: Mark "impl-06-p3-polish" as `completed`
+- Mark "impl-07-tasks-update" as `in_progress`
+
+### Progress Updates
+
+Mark each task in `docs/sprint/Sprint-XX/TASKS.md` as completed:
+```markdown
+- [x] Task 1: [Name]  COMPLETE
+- [ ] Task 2: [Name]  IN PROGRESS
+```
+
+**After updating TASKS.md:**
+- Update todolist: Mark "impl-07-tasks-update" as `completed`
+
+### FINAL STOP POINT
+
+After implementation:
+- Final todolist update: Verify all tasks marked as `completed`
+> **STOP:** Use the question tool to ask "Implementation complete!  Run final verification (Phase X) with all validation scripts?"
+
+**User options:**
+- "yes" → Run Phase X (add verification tasks to todolist)
+- "no" → Wait for manual `/test`
+
+---
+
+## Workflow Reference (Migrated)
+
+# /impl - Implementation
+
+$ARGUMENTS
+
+---
+
+## Overview
+
+This command implements features, fixes bugs, or enhances existing code. It combines "Codegen" (New Features) and "Enhance" (Iterative Updates).
+
+---
+
+## Workflow
+
+### 1. Analysis & Preparation
+- ** Reasoning Loop**:
+  - *Context*: Confirm `docs/sprint` and relevant `docs/requirements`.
+  - *Strategy*: Decide between new file vs modification and pick the pattern (MVC, Component, Hook).
+  - *Dependencies*: Identify other files impacted by the change.
+- **Read Context**: Check `docs/sprint/` tasks and `docs/requirements/`.
+- **Identify Scope**: Decide whether this is a new feature (Codegen) or an update (Enhance).
+- **Load State**: Understand current codebase state.
+
+**After analysis:**
+- Update todolist: Mark "impl-02-analysis" as `completed`
+- Mark "impl-03-p0-foundation" as `in_progress`
+
+### 2. Execution (The Loop)
+
+**For New Features (Codegen Mode):**
+1. **Before React**: Invoke `nextjs-react-expert`.
+2. **Implement**: Write FE/BE code (complete, no TODOs).
+3. **Docs**: Update API docs or README if needed.
+4. **Status**: Update `docs/sprint/<Sprint-N>/TASKS.md` (MUST follow `rules/MASTER.md` documentation rule).
+
+**For Updates (Enhance Mode):**
+1. **Plan Changes**: Determine affected files.
+2. **Present Plan** (if complex): "I will modify X files. proceed?"
+3. **Apply**: Edit files using `replace_file_content` or `multi_replace`.
+4. **Test**: Verify locally if possible.
+
+---
+
+## Output Requirements
+
+- **Production Ready**: No `TODO` comments, strict typing, handled errors.
+- **Security**: Validations, Sanitization, Auth checks (follow stack-appropriate patterns).
+- **Best Practices**:
+    - Use the stack defined in `docs/requirements/<feature>/TechStack.md` or existing project stack
+    - Follow patterns appropriate for chosen technologies
+    - Maintain consistency with existing codebase
+
+**Note:** Best practices are technology-specific. For example:
+- With TanStack Query: Use query keys, staleTime, cache management
+- With Redux: Use selectors, action creators, proper state structure
+- With FastAPI: Use Pydantic schemas, dependency injection, routers
+- With Express: Use middleware, proper error handling, async/await
+
+Always follow the patterns that match the chosen stack.
+
+---
+
+## Usage Examples
+
+```bash
+/impl create user profile page
+/impl add dark mode to settings
+/impl fix validation error in checkout
+/impl refactor auth service
+```

package/.opencode/commands/plan.md

@@ -0,0 +1,250 @@
+---
+description: Create structured task plans with INPUT→OUTPUT→VERIFY criteria
+subtask: false
+---
+
+**PLANNING MODE ACTIVATED**
+
+**User task:** $ARGUMENTS
+
+**If $ARGUMENTS is empty:**
+Use the question tool to ask: "What would you like to plan? Describe the task in detail (e.g., 'create a JWT auth system', 'add dark mode', etc.)"
+
+**Mandatory protocol:**
+
+### Phase 0: TodoList Setup (MANDATORY)
+
+Before any planning work:
+
+1. **Read existing todolist:**
+   ```javascript
+   todoread()
+   ```
+
+2. **Create planning todolist:**
+   ```javascript
+   todowrite({
+     todos: [
+       {
+         id: "plan-01-stack",
+         content: "Select technology stack (if new project)",
+         status: "pending",
+         priority: "high"
+       },
+       {
+         id: "plan-02-clarify",
+         content: "Socratic gate: clarify requirements",
+         status: "pending",
+         priority: "high"
+       },
+       {
+         id: "plan-03-analyze",
+         content: "Analyze project type and identify agents",
+         status: "pending",
+         priority: "high"
+       },
+       {
+         id: "plan-04-requirements",
+         content: "Create requirements artifacts in docs/requirements/",
+         status: "pending",
+         priority: "high"
+       },
+       {
+         id: "plan-05-sprint",
+         content: "Create/update sprint artifacts in docs/sprint/",
+         status: "pending",
+         priority: "high"
+       }
+     ]
+   })
+   ```
+
+3. **Update todolist** as you complete each step (mark `in_progress` → `completed`)
+
+### Phase 1: Stack Selection (NEW PROJECTS ONLY)
+
+**Check if this is a new project (no existing code):**
+
+1. **Look for existing stack:**
+   - Check for `package.json`, `pyproject.toml`, `go.mod`, `Dockerfile`, etc.
+   - If exists → Skip stack selection, maintain consistency
+
+2. **For new projects, use stack-selection skill:**
+   ```javascript
+   question({
+     questions: [{
+         question: "Do you have any tech stack preferences?",
+         header: "Stack Preferences",
+         options: [
+           {
+             label: "I have specific preferences",
+             description: "I'll tell you exactly what tech stack I want"
+           },
+           {
+             label: "Suggest based on requirements",
+             description: "Help me choose based on what I'm building"
+           }
+         ]
+       }]
+   })
+   ```
+
+3. **Document stack decision** in `docs/requirements/<feature>/TechStack.md`:
+   - Frontend stack (framework, build tool, state management, UI library, styling)
+   - Backend stack (runtime, framework, database, ORM)
+   - Infrastructure (containerization, deployment)
+   - Rationale for each choice
+
+### Phase 2: Socratic Gate
+- Use the question tool to ask clarifying questions if needed:
+  1. What is the main goal.
+  2. Any technology preferences (if not set in Phase 1).
+  3. Any constraints or priorities.
+
+### Phase 2: Analysis
+- Determine project type: WEB / MOBILE / BACKEND
+- Identify required agents
+- List core components
+
+### Phase 3: Plan Creation
+Ensure `docs/` exists and follow the planning standard:
+
+**Before creating artifacts:**
+- Update todolist: Mark "plan-03-analyze" as `completed`
+- Mark "plan-04-requirements" as `in_progress`
+
+1. **Discovery/Requirements (MANDATORY)**
+    - Create/update `docs/requirements/<feature>/` with:
+      `PROBLEM_STATEMENT.md`, `USER_STORIES.md`, `ACCEPTANCE_CRITERIA.md`,
+      `DATA_CONTRACTS.md`, `RISKS.md`, `PLAN.md`.
+
+**Required artifacts (SDD Gate):**
+- `docs/requirements/<feature>/PLAN.md`
+- `docs/requirements/<feature>/PROBLEM_STATEMENT.md`
+- `docs/requirements/<feature>/USER_STORIES.md`
+- `docs/requirements/<feature>/ACCEPTANCE_CRITERIA.md`
+- `docs/requirements/<feature>/RISKS.md`
+
+**Auxiliary artifacts (create when applicable):**
+- `docs/requirements/<feature>/research.md`
+- `docs/requirements/<feature>/contracts/`
+- `docs/requirements/<feature>/quickstart.md`
+
+**When to create auxiliary artifacts:**
+- Create `research.md` when there are unresolved unknowns or external dependencies.
+- Update `DATA_CONTRACTS.md` when the feature introduces or changes data entities.
+- Create `contracts/` when the feature introduces APIs, events, or integrations.
+- Create `quickstart.md` when setup or verification needs explicit steps.
+
+**Contracts template usage:**
+- When creating `docs/requirements/<feature>/contracts/`, use `.opencode/templates/SDD-Contracts.md` as the base content.
+
+**Templates (REQUIRED):**
+- `.opencode/templates/SDD-ProblemStatement.md`
+- `.opencode/templates/SDD-UserStories.md`
+- `.opencode/templates/SDD-AcceptanceCriteria.md`
+- `.opencode/templates/SDD-Risks.md`
+- `.opencode/templates/SDD-Plan.md`
+- `.opencode/templates/SDD-Research.md`
+- `.opencode/templates/SDD-Contracts.md` (if applicable)
+- `.opencode/templates/SDD-Quickstart.md` (if applicable)
+
+**After requirements:**
+- Update todolist: Mark "plan-04-requirements" as `completed`
+- Mark "plan-05-sprint" as `in_progress`
+
+2. **Sprint (MANDATORY)**
+    - Use the question tool to ask the user:
+      "Do you want to use the latest sprint or create a new sprint?"
+    - If no sprint exists, create `docs/sprint/Sprint-01/`.
+    - If creating a new sprint, use the next sequential number.
+    - Update `SPRINT_GOAL.md`, `BACKLOG.md`, `TASKS.md`, `RISK_REGISTER.md`.
+
+**Tasks template (REQUIRED for TASKS.md):**
+- `.opencode/templates/SDD-Tasks.md`
+
+**After sprint creation:**
+- Update todolist: Mark "plan-05-sprint" as `completed`
+
+** ABSOLUTE RULES:**
+-  NEVER write code during planning
+-  NEVER use generic names like `plan.md`
+-  ALWAYS use `docs/` as the source of truth
+-  ALWAYS create `docs/` if missing
+
+### MANDATORY STOP POINT
+
+After creating/updating the artifacts:
+> **STOP:** "Plan recorded in `docs/requirements/` and `docs/sprint/Sprint-XX/`. Review it and confirm with 'yes' to proceed with implementation, or tell me what to adjust."
+
+**DO NOT CONTINUE WITHOUT EXPLICIT USER APPROVAL.**
+
+---
+
+## Workflow Reference (Migrated)
+
+# /plan - Unified Planning
+
+$ARGUMENTS
+
+---
+
+## Overview
+
+This command routes to the appropriate planning agent based on the scope:
+1. **Sprint Planning**: Full sprint breakdown (Stories, Epics, Estimations).
+2. **Task Planning**: specific feature or fix breakdown (Steps, Files).
+
+---
+
+## Scenario A: Sprint Planning (Complex/Multi-story)
+
+**Trigger:** User asks for "Sprint Planning", "Backlog", or provides valid context for a full sprint.
+
+### Workflow
+1. **Agent**: `project-planner`
+2. **Action**: Create/Update `docs/sprint/Sprint-XX/` artifacts.
+3. **Steps**:
+    - Check current date/sprint context.
+    - Use the question tool to ask minimal missing inputs (<=5).
+    - Produce `SPRINT_GOAL.md`, `BACKLOG.md`, `TASKS.md`, `RISK_REGISTER.md`.
+4. **Output**: Full set of sprint docs.
+
+---
+
+## Scenario B: Task Planning (Feature/Fix)
+
+**Trigger:** User asks to "plan feature X", "fix bug Y", or "plan architecture for Z".
+
+### Workflow
+1. **Agent**: `project-planner`
+2. **Action**: Create/update `docs/requirements/<feature>/` and align a sprint.
+3. **Steps**:
+    - **Socratic Gate**: Use the question tool to ask clarifying questions first.
+    - **Context Check**: Verify existing code/docs.
+    - **Plan Generation**: Create requirements and sprint artifacts.
+    - **Verify Standard**: Check against `rules/MASTER.md` Documentation Integrity Protocol.
+4. **Naming Rules**:
+    - Feature folders use kebab-case (e.g., `auth-fix`, `cart-feature`).
+    - Sprint folders use `Sprint-XX` with zero padding.
+
+---
+
+## Critical Rules (All Modes)
+
+1. **NO CODE WRITING**: This command ONLY generates documentation/plans.
+2. **Ask Before Planning**: Use the question tool to clear ambiguities.
+3. **File Locations**:
+    - Requirements -> `docs/requirements/<feature>/`
+    - Sprint -> `docs/sprint/Sprint-XX/`
+
+---
+
+## Usage Examples
+
+```bash
+/plan sprint 16 planning
+/plan feature user profile
+/plan fix login bug
+/plan architecture for notifications
+```

package/.opencode/commands/preview.md

@@ -0,0 +1,87 @@
+---
+description: Preview server start, stop, and status check. Local development server management.
+---
+
+# /preview - Preview Management
+
+$ARGUMENTS
+
+## Task
+
+Manage preview server: start, stop, status check.
+
+### Commands
+
+```
+/preview           - Show current status
+/preview start     - Start server
+/preview stop      - Stop server
+/preview restart   - Restart
+/preview check     - Health check
+```
+
+---
+
+## Usage Examples
+
+### Start Server
+```
+/preview start
+
+Response:
+ Starting preview...
+   Port: 3000
+   Type: Next.js
+
+ Preview ready!
+   URL: http://localhost:3000
+```
+
+### Status Check
+```
+/preview
+
+Response:
+=== Preview Status ===
+
+ URL: http://localhost:3000
+ Project: C:/projects/my-app
+ Type: nextjs
+ Health: OK
+```
+
+### Port Conflict
+```
+/preview start
+
+Response:
+ Port 3000 is in use.
+
+Use the question tool to ask:
+```javascript
+question({
+  questions: [{
+      question: "What would you like to do?",
+      header: "Port Conflict",
+      options: [
+        { label: "Start on port 3001", description: "Use alternative port" },
+        { label: "Close app on 3000", description: "Free up the port" },
+        { label: "Specify different port", description: "Custom port number" }
+      ],
+      default: 0
+    }]
+})
+```
+```
+
+---
+
+## Technical
+
+Auto preview uses `auto_preview.py` script which wraps Docker Compose:
+
+```bash
+python .opencode/scripts/auto_preview.py start
+python .opencode/scripts/auto_preview.py stop
+python .opencode/scripts/auto_preview.py status
+```

package/.opencode/commands/specify.md

@@ -0,0 +1,66 @@
+---
+description: Create a feature specification focused on what and why.
+subtask: false
+---
+
+# /specify - Feature Specification
+
+$ARGUMENTS
+
+## Purpose
+
+Create a feature specification that captures user intent, scenarios, and acceptance criteria.
+This command MUST focus on what and why. No implementation details.
+
+## If $ARGUMENTS is empty
+
+Use the question tool to ask for a feature description.
+
+```javascript
+question({
+  questions: [{
+      question: "Describe the feature you want to build (what and why, no tech stack).",
+      header: "Feature Description"
+    }]
+})
+```
+
+## Outputs (required)
+
+Create or update:
+
+- `docs/requirements/<feature>/PROBLEM_STATEMENT.md`
+- `docs/requirements/<feature>/USER_STORIES.md`
+- `docs/requirements/<feature>/ACCEPTANCE_CRITERIA.md`
+- `docs/requirements/<feature>/RISKS.md`
+
+Ensure `docs/requirements/<feature>/` exists before writing.
+
+## Templates
+
+- `.opencode/templates/SDD-ProblemStatement.md`
+- `.opencode/templates/SDD-UserStories.md`
+- `.opencode/templates/SDD-AcceptanceCriteria.md`
+- `.opencode/templates/SDD-Risks.md`
+
+## Workflow
+
+1. Confirm feature name and scope.
+2. Create `docs/requirements/<feature>/` if missing.
+3. Fill templates for Problem Statement, User Stories, Acceptance Criteria, and Risks.
+4. Write prioritized user stories with independent acceptance scenarios.
+5. Capture functional requirements and edge cases.
+6. Record measurable success criteria (tech-agnostic).
+7. Note risks and assumptions.
+
+## Rules
+
+- Do not include tech stack, APIs, or file structure.
+- If ambiguity is critical, mark it as `NEEDS CLARIFICATION` and defer to `/clarify`.
+- Use the question tool for any multi-option decision.
+
+## STOP POINT
+
+After writing the spec:
+
+> Use the question tool to ask "Specification recorded in docs/requirements/. Proceed to /clarify or /plan?"