@paulojalowyj/openkit 0.1.1

package/.opencode/ARCHITECTURE.md

@@ -0,0 +1,150 @@
+# Opencode System Architecture
+
+> Comprehensive AI Agent Capability Expansion Toolkit (Optimized for Z.AI Coding Plan)
+
+---
+
+## Overview
+
+Opencode Agent System is a modular system consisting of:
+
+- **15 Specialist Agents** - Domain-specific prompts for implementation
+- **Primary Agents** - Build, Plan, Chat, and Orchestrator for interactive workflows
+- **33 Skills** - Domain-specific knowledge modules
+- **18 Commands** - Streamlined slash command procedures
+- **1 Master Ruleset** - Fonte única para qualidade e consistência
+
+---
+
+## Directory Structure
+
+```plaintext
+.opencode/
+├── ARCHITECTURE.md          # This file
+├── prompts/                 # Agent prompts
+├── skills/                  # Capability Modules
+├── commands/                # Slash Commands (/slash)
+├── rules/                   # MASTER.md (única fonte de regras)
+├── scripts/                 # Automation & Validation
+
+```
+
+---
+
+## Agents (15)
+
+Optimized for domain separation and execution quality.
+
+| Agent | Focus | Key Skills |
+| ----- | ----- | ---------- |
+| `backend-specialist` | Python/FastAPI, SQL | api-patterns, database-design, python-patterns |
+| `frontend-specialist` | React (TanStack), UI | frontend-design, nextjs-react-expert, tailwind-patterns |
+| `test-engineer` | QA, E2E (Playwright) | testing-patterns, webapp-testing, tdd-workflow |
+| `mobile-developer` | iOS, Android, RN | mobile-design |
+| `devops-engineer` | Docker, CI/CD | deployment-procedures, server-management |
+| `security-auditor` | Compliance, OWASP | vulnerability-scanner, red-team-tactics |
+| `penetration-tester` | Offensive Security | red-team-tactics |
+| `database-architect` | Schema, Migrations | database-design |
+| `project-planner` | Task Breakdown | brainstorming, plan-writing, architecture |
+| `product-owner` | Requirements, Backlog | plan-writing, brainstorming |
+| `explorer-agent` | Code Analysis | architecture, systematic-debugging |
+| `debugger` | Root Cause Analysis | systematic-debugging |
+| `performance-optimizer` | Web Vitals | performance-profiling |
+| `seo-specialist` | Ranking, Geo | seo-fundamentals, geo-fundamentals |
+| `documentation-writer` | Manuals, Docs | documentation-templates |
+
+---
+
+## Skills (Highlights)
+
+Modular knowledge domains loaded on-demand.
+
+**Stack Selection (NEW):**
+| Skill | Purpose |
+|-------|---------|
+| `stack-selection` | Tech stack selection with decision trees, user preferences, and blueprint defaults |
+
+**Core Skills:**
+
+### Frontend & Design (Migrated Engine)
+| Skill | Capabilities |
+| ----- | ------------ |
+| `frontend-design` | **UI/UX Engine**: 50+ styles, 97 palettes, auto-design system generator |
+| `nextjs-react-expert` | React performance, Vercel engineering best practices |
+| `tailwind-patterns` | Tailwind v4 utilities, design tokens |
+
+### Backend & Data
+| Skill | Capabilities |
+| ----- | ------------ |
+| `python-patterns` | FastAPI best practices, Pydantic, Async/Await |
+| `database-design` | Schema optimization, Alembic migrations |
+| `api-patterns` | RESTful design, Error handling standards |
+
+### Quality & Security
+| Skill | Capabilities |
+| ----- | ------------ |
+| `webapp-testing` | Playwright E2E automation, browser testing |
+| `vulnerability-scanner` | Security auditing, dependency analysis |
+| `clean-code` | Universal coding standards (mandatory) |
+
+---
+
+## Commands
+
+Streamlined commands for OpenCode workflows. Invoke with `/command`.
+
+| Command | Purpose |
+| ------- | ------- |
+| `/engineer` | **Universal Builder**: CoT (Chain of Thought) driven planning + execution |
+| `/impl` | **Feature Implementation**: Reasoning Loop for safe code changes |
+| `/plan` | **Task Planning**: Detailed breakdowns and sprint alignment |
+| `/test` | **Quality Assurance**: Run unit checks and E2E suites |
+| `/ui-ux` | **Design Studio**: Generate design systems and UI components |
+| `/deploy` | **Production**: Safe deployment procedures and verifications |
+| `/debug` | **Systematic Debugging**: 4-phase root cause analysis |
+| `/context` | **Repo Analysis**: Generate context packs for LLMs |
+| `/doc` | **Documentation**: Write manuals and API docs |
+| `/status` | **Progress Tracking**: View active tasks and stats |
+| `/preview` | **Dev Environment**: Manage Docker Compose (`scripts/auto_preview.py`) |
+
+---
+
+## Core Rules (Mandatory)
+
+Tudo consolidado em `.opencode/rules/MASTER.md`:
+
+1.  Runtime model choice and Socratic Gate.
+2.  Regras universais de linguagem, clean code e dependências.
+3.  Protocolo de roteamento de agentes e carregamento de skills.
+4.  Documentação de sprints, planos e artefatos oficiais.
+5.  Checklist final e scripts obrigatórios (Security -> Lint -> Tests -> UX -> SEO).
+6.  **User Interaction Protocol (MANDATORY)**: Use `question` tool for ALL user choices, preferences, and clarifications. NEVER ask multi-option questions inline.
+
+---
+
+## Automation Scripts
+
+Located in `.opencode/scripts/`.
+
+| Script | Usage | Description |
+| ------ | ----- | ----------- |
+| `auto_preview.py` | `python .opencode/scripts/auto_preview.py start` | Manages full-stack env via Docker Compose |
+| `checklist.py` | `python .opencode/scripts/checklist.py .` | Fast validation (Lint, Tests, Security) |
+| `verify_all.py` | `python .opencode/scripts/verify_all.py . --url <URL>` | Full suite (Lighthouse, E2E, SEO, Mobile) |
+| `session_manager.py` | `python .opencode/scripts/session_manager.py status` | Project stats and stack detection |
+
+---
+
+## Quick Reference
+
+**"I want to build a new feature"**
+> Use `/plan` then `/impl` (or `/engineer` for complex tasks).
+
+**"I want to design a UI"**
+> Use `/ui-ux` to generate a system, then `frontend-specialist`.
+
+**"I want to test everything"**
+> Use `/test` locally, then `/deploy` for verification.
+
+**"I want to verify the project"**
+> Run `python .opencode/scripts/checklist.py .`

package/.opencode/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paulo Jalowyj
+
+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.

package/.opencode/bin/cli.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { copyFileSync, existsSync, mkdirSync, readdirSync } from 'fs';
+import { dirname } from 'path';
+import inquirer from 'inquirer';
+import { execSync } from 'child_process';
+import fs from 'fs-extra';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const program = new Command();
+
+function checkOpenCodeInstalled() {
+  try {
+    execSync('which opencode || where opencode', {
+      stdio: 'ignore',
+      shell: true
+    });
+    return true;
+  } catch (e) {
+  }
+
+  try {
+    execSync('npm list -g @opencode-ai/plugin', {
+      stdio: 'ignore',
+      shell: true
+    });
+    return true;
+  } catch (e) {
+  }
+
+  return false;
+}
+
+async function installOpenCode() {
+  console.log(chalk.yellow('\nInstalando OpenCode...'));
+
+  try {
+    execSync('curl -fsSL https://opencode.ai/install | bash', {
+      stdio: 'inherit',
+      shell: true
+    });
+
+    if (!checkOpenCodeInstalled()) {
+      throw new Error('Installação concluída mas OpenCode não detectado');
+    }
+
+    console.log(chalk.green('OpenCode instalado com sucesso!\n'));
+  } catch (error) {
+    console.log(`\n${chalk.red('Falha na instalação do OpenCode.')}`);
+    console.log(chalk.white(`Error: ${error.message}\n`));
+    console.log(chalk.yellow('Instale manualmente:'));
+    console.log(chalk.white('   curl -fsSL https://opencode.ai/install | bash\n'));
+    throw error;
+  }
+}
+
+async function promptInstallOpenCode() {
+  const { install } = await inquirer.prompt([{
+    type: 'confirm',
+    name: 'install',
+    message: 'OpenCode não está instalado. Deseja instalar agora?',
+    default: true
+  }]);
+  return install;
+}
+
+function showOpenCodeNotInstalledError() {
+  console.log(chalk.red('\nOpenCode não está instalado no seu sistema.\n'));
+  console.log(chalk.cyan('Para usar este pacote, você precisa ter o OpenCode instalado.\n'));
+  console.log(chalk.yellow('Instalação manual:'));
+  console.log(chalk.white('  curl -fsSL https://opencode.ai/install | bash\n'));
+}
+
+program
+  .name('openkit')
+  .description('Initialize OpenCode Agent System in your project')
+  .version('0.1.1');
+
+program
+  .command('init')
+  .description('Initialize OpenCode configuration in current directory')
+  .option('-f, --force', 'Overwrite existing .opencode directory')
+  .action(async (options) => {
+    console.log(chalk.blue('Initializing OpenCode Agent System...'));
+
+    const isInstalled = checkOpenCodeInstalled();
+
+    if (!isInstalled) {
+      const shouldInstall = await promptInstallOpenCode();
+
+      if (shouldInstall) {
+        try {
+          await installOpenCode();
+        } catch (error) {
+          console.log(chalk.red('\nInitialization aborted due to installation failure.\n'));
+          process.exit(1);
+        }
+      } else {
+        showOpenCodeNotInstalledError();
+        process.exit(1);
+      }
+    }
+
+    const projectDir = process.cwd();
+    const opencodeDir = path.join(projectDir, '.opencode');
+    const templateDir = path.join(__dirname, '..', '.opencode');
+
+    if (existsSync(opencodeDir) && !options.force) {
+      console.log(chalk.yellow('Warning: .opencode directory already exists'));
+      console.log('Use --force to overwrite');
+      process.exit(1);
+    }
+
+    if (existsSync(opencodeDir) && options.force) {
+      console.log(chalk.yellow('Removing existing .opencode directory...'));
+      await removeDir(opencodeDir);
+    }
+
+    mkdirSync(opencodeDir, { recursive: true });
+
+    console.log(chalk.green('Copying OpenCode configuration...'));
+    await copyDir(templateDir, opencodeDir);
+
+    console.log(chalk.green('Successfully initialized OpenCode!'));
+    console.log(chalk.cyan('\nNext steps:'));
+    console.log('  1. Restart OpenCode TUI');
+    console.log('  2. Use /engineer, /plan, /debug, and other commands\n');
+  });
+
+program
+  .command('doctor')
+  .description('Check OpenCode installation')
+  .action(async () => {
+    console.log(chalk.blue('Checking OpenCode installation...\n'));
+
+    const projectDir = process.cwd();
+    const opencodeDir = path.join(projectDir, '.opencode');
+
+    const checks = [
+      {
+        name: '.opencode directory',
+        check: () => existsSync(opencodeDir),
+        file: true,
+      },
+      {
+        name: 'Commands',
+        check: () => existsSync(path.join(opencodeDir, 'commands/debug.md')),
+        file: true,
+      },
+      {
+        name: 'Prompts',
+        check: () => existsSync(path.join(opencodeDir, 'prompts/backend-specialist.md')),
+        file: true,
+      },
+      {
+        name: 'Skills',
+        check: () => existsSync(path.join(opencodeDir, 'skills/')),
+        dir: true,
+      },
+      {
+        name: 'Config',
+        check: () => existsSync(path.join(projectDir, 'opencode.json')),
+        file: true,
+      },
+    ];
+
+    let allPassed = true;
+
+    for (const check of checks) {
+      const result = check.check();
+      if (result) {
+        console.log(chalk.green(`OK   ${check.name}`));
+      } else {
+        console.log(chalk.red(`FAIL ${check.name}`));
+        allPassed = false;
+      }
+    }
+
+    console.log('');
+    if (allPassed) {
+      console.log(chalk.green('All checks passed.'));
+    } else {
+      console.log(chalk.yellow('Some checks failed. Run `npx @paulojalowyj/openkit init`'));
+    }
+  });
+
+async function copyDir(src, dest) {
+  mkdirSync(dest, { recursive: true });
+  const entries = readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+async function removeDir(dir) {
+  await fs.remove(dir);
+}
+
+program.parse(process.argv);

package/.opencode/commands/README.md

@@ -0,0 +1,273 @@
+# Custom Commands - OpenKit
+
+> Slash commands for the OpenCode TUI
+> OpenKit integration with structured commands
+
+---
+
+## Available Commands
+
+When you type `/` in the OpenCode TUI, you will see:
+
+| Command | Description | Usage |
+|---------|-------------|-------|
+| `/engineer` | Universal orchestrator for complex tasks | `/engineer build full e-commerce` |
+| `/specify` | Create feature specification | `/specify add user profiles` |
+| `/clarify` | Clarify requirements in spec | `/clarify` |
+| `/plan` | Create structured task plans | `/plan create auth system` |
+| `/tasks` | Generate executable tasks | `/tasks` |
+| `/analyze` | Cross-artifact consistency | `/analyze` |
+| `/checklist` | Spec/plan quality checklist | `/checklist` |
+| `/impl` | Execute implementation from a plan | `/impl from docs/sprint/Sprint-17/TASKS.md` |
+| `/test` | Run tests and checks | `/test all` or `/test security` |
+| `/debug` | 4-phase systematic debugging | `/debug login not working` |
+| `/ui-ux` | Design systems and UX audits | `/ui-ux create design system` |
+| `/deploy` | Safe deploy with verification | `/deploy staging` or `/deploy production` |
+| `/context` | Generate repo context pack | `/context` |
+| `/doc` | Write or update docs | `/doc update api index` |
+| `/preview` | Manage local preview server | `/preview start` |
+| `/status` | Show project status | `/status` |
+| `/create` | Create a new application | `/create blog site` |
+| `/brainstorm` | Explore ideas and options | `/brainstorm auth system` |
+
+---
+
+## How to Use
+
+### 1. With Arguments (Direct)
+```bash
+/plan create JWT auth system
+/engineer build e-commerce with Stripe checkout
+```
+
+### 2. Without Arguments (Interactive)
+```bash
+/plan
+→ (via question tool) "What would you like to plan?"
+→ You describe it
+→ System executes
+```
+
+### 3. Full Flow
+```bash
+# 1. Specify
+/specify add dark mode feature
+→ Creates docs/requirements/<feature>/
+→ STOP: "Proceed to clarify or plan?"
+
+# 2. Clarify
+/clarify
+→ Resolves ambiguities in spec
+→ STOP: "Proceed to plan?"
+
+# 3. Plan
+/plan add dark mode feature
+→ Creates plan + auxiliary artifacts when applicable
+→ STOP: "Review and confirm?"
+
+# 4. Tasks
+/tasks
+→ Generates docs/sprint/Sprint-XX/TASKS.md
+→ STOP: "Proceed to implement?"
+
+# 5. Implement (after approval)
+/impl from docs/sprint/Sprint-XX/TASKS.md
+→ Executes plan tasks
+→ STOP between phases (P0→P1→P2→P3)
+
+# 6. Analyze + Checklist
+/analyze
+→ Validates spec/plan/tasks consistency
+/checklist
+→ Confirms readiness and gaps
+
+# 7. Test
+/test all
+→ Runs all checks
+→ Reports results
+
+# 8. Deploy (if approved)
+/deploy production
+→ Pre-deploy checklist
+→ STOP: "Confirm production deploy?"
+→ Executes deploy
+→ Post-deploy verification
+```
+
+---
+
+## Hybrid Behavior
+
+All commands follow a hybrid behavior:
+
+1. **Show:** Load and explain the appropriate command protocol
+2. **Ask (via question tool):** Mandatory STOP points for approval
+3. **Execute:** Only after user confirmation
+
+---
+
+## STOP Points
+
+The system always pauses for approval at critical moments:
+
+### `/plan`
+> "Plan recorded in `docs/requirements/` and `docs/sprint/Sprint-XX/`. Review and confirm to proceed?"
+
+### `/impl`
+- Between each phase (P0, P1, P2, P3)
+- At the end: "Run final verification?"
+
+### `/deploy`
+- Production requires explicit confirmation
+- After deploy: "Confirm success?"
+
+---
+
+## File Structure
+
+```
+.opencode/
+└── commands/
+    ├── analyze.md     # Spec/plan/tasks analysis
+    ├── brainstorm.md  # Idea exploration
+    ├── checklist.md   # Spec/plan checklist
+    ├── clarify.md     # Spec clarification
+    ├── context.md     # Context pack generation
+    ├── create.md      # New app creation
+    ├── doc.md         # Documentation updates
+    ├── engineer.md    # Universal orchestrator
+    ├── impl.md        # Implementation command
+    ├── plan.md        # Planning command
+    ├── preview.md     # Preview management
+    ├── specify.md     # Feature specification
+    ├── status.md      # Status reporting
+    ├── tasks.md       # Task generation
+    ├── test.md        # Testing command
+    ├── ui-ux.md       # Design command
+    └── deploy.md      # Deploy command
+```
+
+```
+.opencode/
+├── agents/            # Specialist agents
+├── skills/            # Knowledge modules
+└── scripts/           # Python validation scripts
+```
+
+---
+
+## Command Features
+
+### Placeholders
+- `$ARGUMENTS` - All user arguments
+- `$1`, `$2`, `$3` - Positional arguments
+
+### Shell Integration
+- `!command` - Inject shell output
+- Example: `!git log --oneline -10`
+
+### File References
+- `@file` - Include file content
+- Example: `@src/components/Button.tsx`
+
+---
+
+## Configuration
+
+### Local (This Project)
+Files in `.opencode/commands/` are available only in this project.
+
+### Global (All Projects)
+Copy to `~/.config/opencode/commands/` to use everywhere:
+
+```bash
+cp -r .opencode/commands/* ~/.config/opencode/commands/
+```
+
+---
+
+## Usage Examples
+
+### Example 1: Simple Feature
+```bash
+# Plan
+/plan add dark mode toggle
+→ Updates docs artifacts
+
+# Approve and implement
+/impl from docs/sprint/Sprint-XX/TASKS.md
+→ Executes tasks
+
+# Test
+/test coverage
+→ 95% coverage, all passing
+```
+
+### Example 2: Complex System
+```bash
+# Orchestrate everything
+/engineer build e-commerce with Stripe
+→ Phase 1: Planning (project-planner)
+→ STOP: "Proceed?"
+→ Phase 2: Implementation (multiple agents)
+→ STOP: "Verify?"
+→ Phase 3: Verification (Phase X)
+→ Project complete! 
+```
+
+### Example 3: Debug
+```bash
+/debug users can't login after last update
+→ Phase 1: Symptom Analysis
+→ Phase 2: Information Gathering
+→ Phase 3: Hypothesis Testing
+→ Phase 4: Resolution
+→ Bug fixed! 
+```
+
+---
+
+## Tips
+
+1. **Use `/engineer` for complex tasks** - It coordinates multiple agents
+2. **Use `/plan` first** - Always plan before implementing
+3. **Do not skip STOPs** - Manual approvals ensure quality
+4. **Keep plans small** - If > 10 tasks, split into parts
+5. **Run `/test` often** - Catch issues early
+
+---
+
+## 🆘 Troubleshooting
+
+### "Command does not appear after typing /"
+→ Restart the OpenCode TUI
+
+### "Command not found"
+→ Verify that `.opencode/commands/` exists
+
+### "Python scripts do not run"
+→ Ensure Python is installed and dependencies are satisfied
+
+---
+
+## OpenKit Integration
+
+These commands reuse:
+-  Specialist prompts (`.opencode/prompts/`)
+-  Skills (`.opencode/skills/`)
+-  Python validation scripts (`.opencode/scripts/`)
+-  Original rules and protocols
+
+They are only adapted to the OpenCode command format.
+
+---
+
+## Additional Documentation
+
+- **OpenKit Architecture:** `.opencode/ARCHITECTURE.md`
+
+---
+
+## Ready to use!
+
+Open the OpenCode TUI and type `/` to see all available commands.