@paulojalowyj/openkit 0.1.1

package/.opencode/rules/MASTER.md

@@ -0,0 +1,272 @@
+---
+trigger: always_on
+---
+
+# MASTER RULESET — OPENCODE AGENT SYSTEM
+
+> Single source of mandatory rules for all agents, skills, and commands.
+
+---
+
+## Tool Usage (MANDATORY)
+
+**All agents, commands, and skills MUST follow:** `.opencode/rules/TOOL_USAGE.md`
+
+This rule defines:
+- Correct tool selection (glob vs grep vs read vs bash)
+- File operation patterns (read -> edit/write)
+- User interaction (question tool vs inline)
+- Task tracking (todolist tools vs inline)
+- Common mistakes and fixes
+
+**Key principles:**
+- Use `glob` for file patterns, NOT `bash find`
+- Use `grep` for content search, NOT `bash grep`
+- Use `read` for file reading, NOT `bash cat`
+- Use `edit` for existing files, `write` for new files
+- Use `question` tool for multiple options, NOT inline questions
+- Use `todolist` tools for complex tasks (3+ steps), NOT inline tracking
+- Use `workdir` parameter, NOT `cd && command`
+
+---
+
+## Context & Language
+
+- Respond in the user's language; keep code/comments in English.
+- Follow `@[skills/clean-code]`: SRP, DRY, KISS, functions <= 20 lines, max 3 args, use guard clauses.
+- Before changing any file, understand dependencies via `CODEBASE.md` or local references.
+- Philosophy `Read → Understand → Apply`: identify objective, principles, and differences from generic output.
+
+## Response Style (MANDATORY)
+
+- Be objective, technical, consistent, and direct.
+- Avoid embellishment, filler, and marketing language.
+- Prefer short, information-dense sentences.
+
+## Emoji Policy (MANDATORY)
+
+- Do not use emojis in assistant responses.
+- Do not introduce emojis into documentation.
+- Exception: only use emojis if the user explicitly requests them.
+
+---
+
+## Question Tool Protocol (MANDATORY)
+
+### When to Use `question` Tool
+
+**MUST use `question` tool (never inline questions) when:**
+
+| Situation | Example |
+|-----------|----------|
+| User must choose from **multiple options** | "Which framework: FastAPI or Django?" |
+| User needs to make a **decision** | "Deploy to staging or production?" |
+| **Ambiguous instructions** need clarification | "What authentication method: JWT or OAuth?" |
+| **STOP points** requiring explicit approval | "Proceed with implementation?" |
+| **Multiple choices** with trade-offs | "Option A or Option B for caching?" |
+
+Additional enforcement:
+- If you present 2+ next-step options (e.g., "I can do A or B"), you MUST use the `question` tool.
+- Do not present multiple options as plain text and wait for a free-form reply.
+
+### When Inline Questions Are OK
+
+Single yes/no confirmations where context is clear:
+- "Delete this file?" (after showing what will be deleted)
+- "Continue with the plan?" (after presenting it)
+- "What would you like to do?" (has multiple options) -> MUST use `question`
+
+### Question Format
+
+Use `question` tool with proper structure:
+
+```javascript
+question({
+  questions: [{
+    question: "Clear, concise question text",
+    header: "Short title (max 30 chars)",
+    options: [
+      { label: "Option 1", description: "Why choose this" },
+      { label: "Option 2", description: "Alternative reason" }
+    ],
+    multiple: false // or true for multi-select
+  }]
+})
+```
+
+**This is a MANDATORY pattern. Agents, skills, and commands MUST follow it.**
+
+---
+
+## TodoList Protocol (MANDATORY)
+
+**Complete protocol:** `.opencode/rules/TODOLIST_PROTOCOL.md`
+
+### When to Use `todowrite`/`todoread` Tools
+
+**MUST use todolist tools (never inline tracking) when:**
+
+| Situation | Example |
+|-----------|----------|
+| **Multi-step tasks** (3+ steps) | "Build e-commerce checkout with 5+ components" |
+| **Complex planning phases** | Sprint planning with 5+ stories |
+| **Orchestration mode** | Coordinating 3+ agents (backend, frontend, security) |
+| **Tracking execution** | Marking progress across agent invocations |
+| **Parallel workflows** | Managing multiple simultaneous tasks with dependencies |
+| **STOP points with multiple outcomes** | "P0 complete. Proceed to P1, P2, or stop?" |
+
+CRITICAL: After creating todolist, MUST use `question` tool to request user approval before execution.
+
+### When Inline Tracking Is OK
+
+Single-task operations where progress is obvious:
+- "Installing dependencies..." (immediate single step)
+- "Running tests..." (one command, output shows result)
+- "Building feature with 5 steps" -> MUST use todolist
+
+### TodoList Lifecycle
+
+**1. Create:**
+- Use `todowrite` at START of complex tasks (3+ steps)
+- Include: task id, description (NO emojis), status, priority
+
+**2. Request Approval (MANDATORY):**
+- Use `question` tool to ask user approval
+- Wait for user response before executing
+
+**3. Update:**
+- Mark tasks as `in_progress` when starting
+- Mark tasks as `completed` when done (NO emojis in content)
+- Always `todoread` before updating to check current state
+
+**4. Read:**
+- Use `todoread` to check current state before any action
+- Verify no duplicate or conflicting tasks exist
+
+### TodoList Format
+
+Use `todowrite` tool with proper structure:
+
+```javascript
+todowrite({
+  todos: [
+    {
+      id: "task-1",
+      content: "Brief task description (max 50 chars)",
+      status: "pending",
+      priority: "high"
+    },
+    {
+      id: "task-2",
+      content: "Another task description",
+      status: "in_progress",
+      priority: "medium"
+    }
+  ]
+})
+```
+
+**Status values:** `pending`, `in_progress`, `completed`, `cancelled`  
+**Priority values:** `high`, `medium`, `low`
+
+CRITICAL RULES:
+- NO emojis in task content
+- MUST use `question` tool for approval after creating todolist
+- Only ONE task `in_progress` at a time
+
+**See complete protocol:** `.opencode/rules/TODOLIST_PROTOCOL.md`
+
+**This is a MANDATORY pattern. Agents, skills, and commands MUST follow it.**
+
+---
+
+## Runtime Model Choice
+
+Model selection is handled by runtime/user environment. Agents and prompts must not emit model recommendation suggestions during execution.
+
+---
+
+## Agent & Skill Protocol
+
+1. Detect the domain (frontend, backend, mobile, security, etc.).
+2. Read the corresponding prompt file (`.opencode/prompts/<agent>.md`).
+3. Load all skills listed in the frontmatter (`SKILL.md`).
+4. Announce: `Applying knowledge of @[agent-name]...` before any specialized output.
+5. Follow `@[skills/intelligent-routing]` and keep the checklist:
+   - Correct agent? → If not, re-evaluate.
+   - Agent file read? → Open and review.
+   - Skills loaded? → Read each relevant `SKILL.md`.
+   - Announcement made? → Inform the user.
+
+### Socratic Gate
+Always ask clarifying questions before execution when there is significant ambiguity. Use `@[skills/brainstorming]` for discovery.
+
+---
+
+## Project Structure & Standards
+
+- **frontend/**: Use stack defined in project (check existing code or `docs/requirements/`). Follow `frontend-specialist` rules.
+- **backend/**: Use stack defined in project (check existing code or `docs/requirements/`). Follow `backend-specialist` rules.
+- **docs/**: Source of truth for discovery, planning, and documentation. Create `docs/` if missing.
+- **Stack Selection**: For new projects, use `@[skills/stack-selection]` to determine appropriate technologies with user input.
+- Record cross-scope impacts in `docs/ACTION_ITEMS.md` (when it exists).
+- Branches `feat/<area>-<slug>`; commits `feat|fix|docs|test|refactor|perf|chore|revert`.
+- No `console.log`/`print`. Use official loggers.
+
+---
+
+## SDD Gate (Mandatory)
+
+Before any `/impl` execution, the following artifacts MUST exist:
+
+- `docs/requirements/<feature>/PROBLEM_STATEMENT.md`
+- `docs/requirements/<feature>/USER_STORIES.md`
+- `docs/requirements/<feature>/ACCEPTANCE_CRITERIA.md`
+- `docs/requirements/<feature>/RISKS.md`
+- `docs/requirements/<feature>/PLAN.md`
+
+If any are missing, STOP and direct the user to run `/specify`, `/clarify`, and `/plan` first.
+
+---
+
+## Sprint Documentation & Artifacts
+
+1. **Identification**: Locate `docs/sprint/Sprint-XX/` and review `SPRINT_GOAL.md`, `BACKLOG.md`, `TASKS.md`.
+2. **Sprint Selection**: Ask the user whether to use the latest sprint or create a new one.
+   - If no sprint exists, create `Sprint-01`.
+   - If creating a new sprint, use the next sequential number.
+3. **Planning**: Create requirements in `docs/requirements/<feature>/` and update Backlog/Tasks.
+4. **Execution**: Mark progress in `TASKS.md`; update story status in `BACKLOG.md`.
+5. **Completion**: Mark tasks as `[x]`, register changes in `docs/CHANGELOG.md` when requested.
+6. **Templates**: Use `@[skills/documentation-templates]` for requirements, sprints, and reports.
+
+CRITICAL: Ending a task without syncing `docs/sprint/` is a protocol violation.
+
+---
+
+## Final Checklist & Scripts
+
+1. Execution order: **Security → Lint → Schema → Tests → UX → SEO → Lighthouse/E2E**.
+2. Main commands:
+   - `python .opencode/scripts/checklist.py .`
+   - `python .opencode/scripts/checklist.py . --url <URL>` (full pre-deploy)
+3. Skill scripts (run based on scope):
+   - Security: `python .opencode/skills/vulnerability-scanner/scripts/security_scan.py .`
+   - Lint/Types: `python .opencode/skills/lint-and-validate/scripts/lint_runner.py .`
+   - Tests: `python .opencode/skills/testing-patterns/scripts/test_runner.py .`
+   - UX/Accessibility: `python .opencode/skills/frontend-design/scripts/ux_audit.py .`
+   - SEO: `python .opencode/skills/seo-fundamentals/scripts/seo_checker.py .`
+   - Mobile/Performance/etc.: see `skills/<skill>/scripts/`.
+
+A task only ends when `checklist.py` succeeds. If it fails, resolve critical blockers (Security/Lint) before proceeding.
+
+---
+
+## Additional Best Practices
+
+- References to commands (`/plan`, `/impl`, `/engineer`, `/test`, `/deploy`, `/doc`, `/ui-ux`, `/preview`, `/status`) must follow `.opencode/commands/`.
+- When generating new artifacts, record times using timezone UTC-3 as per `AGENTS.md`.
+- Update `docs/.context` and `docs/ACTION_ITEMS.md` when there is multi-repo impact.
+- Always validate sensitive data: never expose secrets, tokens, or `.env`.
+
+This file supersedes all previous rules (`CORE`, `ROUTING`, `CHECKLIST`, `SPRINTS`).

package/.opencode/rules/README.md

@@ -0,0 +1,266 @@
+# Rules Directory
+
+> Central repository of mandatory protocols for the OpenCode agent system.
+
+---
+
+## Overview
+
+This directory contains **system-wide rules** that enforce consistent behavior across:
+- **Orchestrator** (`.opencode/prompts/orchestrator.md`)
+- **All specialist prompts** (`.opencode/prompts/*.md`)
+- **All commands** (`.opencode/commands/*.md`)
+- **All skills** (`.opencode/skills/*/SKILL.md`)
+
+---
+
+## Rule Files
+
+### 1. **MASTER.md** (Priority: P0)
+**Purpose:** Single source of truth for all mandatory rules.
+
+**Contains:**
+- Tool usage reference (delegates to TOOL_USAGE.md)
+- Context & language protocols
+- Question tool protocol
+- TodoList protocol
+- Model selection guidelines
+- Agent & skill protocol
+- Project structure standards
+- Sprint documentation requirements
+- Final checklist & scripts
+- Best practices
+
+**Applies to:** All agents, commands, skills
+
+**Trigger:** `always_on`
+
+---
+
+### 2. **TOOL_USAGE.md** (Priority: P0)
+**Purpose:** Definitive guide for correct tool selection and usage patterns.
+
+**Contains:**
+- Tool selection decision tree
+- File discovery & search patterns
+- File operation rules (read → edit/write)
+- Code execution & shell patterns
+- User interaction protocols
+- Task tracking lifecycle
+- Knowledge loading patterns
+- Common mistakes & fixes
+- Validation checklist
+
+**Applies to:** All agents, commands, skills
+
+**Trigger:** `always_on`
+
+**Key Enforcements:**
+-  Use `glob` for file patterns, NOT `bash find`
+-  Use `grep` for content search, NOT `bash grep`
+-  Use `read` for file reading, NOT `bash cat`
+-  Use `edit` for existing files, `write` for new files
+-  Use `question` tool for multiple options, NOT inline questions
+-  Use `todolist` tools for complex tasks (3+ steps), NOT inline tracking
+-  Use `workdir` parameter, NOT `cd && command`
+
+---
+
+## Rule Hierarchy
+
+```
+MASTER.md (Root)
+    ↓
+    ├─ TOOL_USAGE.md (Tool patterns)
+    │
+    ├─ Agent Prompts (.opencode/prompts/*.md)
+    │   └─ Reference MASTER.md + TOOL_USAGE.md
+    │
+    ├─ Command Files (.opencode/commands/*.md)
+    │   └─ Reference MASTER.md + TOOL_USAGE.md
+    │
+    └─ Skill Files (.opencode/skills/*/SKILL.md)
+        └─ Reference MASTER.md + TOOL_USAGE.md
+```
+
+---
+
+## How Rules Are Applied
+
+### 1. **Automatic Loading**
+- All rules with `trigger: always_on` are loaded at system startup
+- `MASTER.md` is ALWAYS active
+- `TOOL_USAGE.md` is ALWAYS active
+
+### 2. **Agent Invocation**
+When an agent is invoked:
+1. System loads `MASTER.md` (automatic)
+2. System loads `TOOL_USAGE.md` (automatic)
+3. Agent reads its own prompt (`.opencode/prompts/<agent>.md`)
+4. Agent loads skills from frontmatter
+
+### 3. **Command Execution**
+When a command is executed:
+1. System loads `MASTER.md` (automatic)
+2. System loads `TOOL_USAGE.md` (automatic)
+3. Command reads its own file (`.opencode/commands/<command>.md`)
+4. Command follows protocols from rules
+
+### 4. **Skill Loading**
+When a skill is loaded:
+1. System loads `MASTER.md` (automatic)
+2. System loads `TOOL_USAGE.md` (automatic)
+3. Skill instructions are read from `SKILL.md`
+4. Skill follows protocols from rules
+
+---
+
+## Enforcement
+
+### Priority Levels
+- **P0 (Critical):** Must be followed. Violations break the system.
+- **P1 (High):** Should be followed. Violations cause inconsistency.
+- **P2 (Medium):** Recommended. Violations reduce quality.
+- **P3 (Low):** Nice to have. Violations are acceptable.
+
+### Conflict Resolution
+1. `MASTER.md` supersedes all other rules
+2. `TOOL_USAGE.md` supersedes agent/command/skill instructions for tool usage
+3. Agent-specific rules override generic patterns (within their domain)
+4. User instructions override all rules (when explicit)
+
+---
+
+## Validation
+
+### For Agents
+Before any action, verify:
+- [ ] Have I read `MASTER.md`? (automatic)
+- [ ] Have I read `TOOL_USAGE.md`? (automatic)
+- [ ] Am I using the correct tool? (check decision tree)
+- [ ] Have I loaded required skills? (check frontmatter)
+- [ ] Am I following todolist protocol? (for complex tasks)
+- [ ] Am I following question tool protocol? (for multiple options)
+
+### For Commands
+Before execution, verify:
+- [ ] Have I read `MASTER.md`? (automatic)
+- [ ] Have I read `TOOL_USAGE.md`? (automatic)
+- [ ] Am I using the correct tool? (check decision tree)
+- [ ] Am I following user interaction patterns? (question/todolist)
+
+### For Skills
+Before applying, verify:
+- [ ] Have I read `MASTER.md`? (automatic)
+- [ ] Have I read `TOOL_USAGE.md`? (automatic)
+- [ ] Am I using the correct tool? (check decision tree)
+- [ ] Am I announcing skill usage? (`Applying knowledge of @[skill-name]...`)
+
+---
+
+## Quick Reference
+
+### Tool Configuration
+
+**Tools are configured in `opencode.json`**, NOT in prompt markdown files.
+
+Example orchestrator configuration:
+```json
+{
+  "agent": {
+    "orchestrator": {
+      "tools": {
+        "read": true,
+        "grep": true,
+        "glob": true,
+        "list": true,
+        "bash": true,
+        "edit": true,
+        "write": true,
+        "patch": true,
+        "webfetch": true,
+        "skill": true,
+        "todowrite": true,
+        "todoread": true,
+        "question": true
+      }
+    }
+  }
+}
+```
+
+### Tool Selection
+| Need | Use | NOT |
+|------|-----|-----|
+| Find files by name | `glob` | `bash find` |
+| Find files by content | `grep` | `bash grep` |
+| List directory | `list` | `bash ls` |
+| Read file | `read` | `bash cat` |
+| Edit existing file | `edit` | `write` (unless rewriting) |
+| Create new file | `write` | `bash echo >` |
+| Apply patch | `patch` | `bash patch` |
+| Execute command | `bash` | Manual execution |
+| Change directory | `workdir` param | `cd &&` |
+| Ask multiple options | `question` tool | Inline text |
+| Track complex tasks | `todolist` tools | Inline text |
+
+### Common Patterns
+```javascript
+//  File discovery
+glob("**/*.tsx")
+grep("useState", "src/**/*.tsx")
+
+//  File operations
+read("file.ts")
+edit("file.ts", "old", "new")
+
+//  User interaction
+question({
+  questions: [{
+    question: "Choose option",
+    header: "Title",
+    options: [...]
+  }]
+})
+
+//  Task tracking
+todoread()
+todowrite({ todos: [...] })
+
+//  Command execution
+bash("pytest tests", workdir="/backend")
+```
+
+---
+
+## Maintenance
+
+### Adding New Rules
+1. Create new `.md` file in `.opencode/rules/`
+2. Add frontmatter with `trigger` and `priority`
+3. Update `MASTER.md` to reference it (if needed)
+4. Update this README with the new rule
+
+### Updating Existing Rules
+1. Edit the rule file directly
+2. Update version/date in frontmatter (if present)
+3. Announce changes to all agents (via system update)
+
+### Deprecating Rules
+1. Mark rule as `deprecated: true` in frontmatter
+2. Add `superseded_by: <new-rule>.md` reference
+3. Keep file for 2 versions, then delete
+
+---
+
+## Related Documentation
+
+- **Agent Prompts**: `.opencode/prompts/`
+- **Command System**: `.opencode/commands/README.md`
+- **Skill System**: `docs/SKILLS.md`
+- **Architecture**: `.opencode/ARCHITECTURE.md`
+
+---
+
+**Last Updated:** 2026-02-04  
+**Maintained By:** OpenCode System