npm - takomi - Versions diffs - 2.0.4 - Mend

takomi 2.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (544) hide show

package/assets/.agent/workflows/LEGACY/seo_ready.md ADDED Viewed

@@ -0,0 +1,249 @@
+---
+description: Make any Next.js page SEO-ready with metadata, structured data, and accessibility
+---
+# SEO Ready Workflow
+This workflow transforms any Next.js page into a fully SEO-optimized page.
+## Prerequisites
+- A Next.js 13+ project using App Router
+- Target page(s) to optimize
+---
+## Phase 1: Global SEO Setup (Run Once Per Project)
+### 1.1 Check for Root Layout Metadata
+// turbo
+```bash
+head -50 src/app/layout.tsx
+```
+Verify the root `layout.tsx` has a comprehensive `metadata` export:
+```typescript
+export const metadata: Metadata = {
+  title: {
+    default: "Site Name",
+    template: "%s | Site Name",  // Allows per-page titles
+  },
+  description: "...",
+  keywords: ["..."],
+  authors: [{ name: "..." }],
+  creator: "...",
+  metadataBase: new URL("https://your-domain.com"),
+  openGraph: { /* ... */ },
+  twitter: { /* ... */ },
+};
+```
+**If missing**, add a full metadata block to `src/app/layout.tsx`.
+### 1.2 Check for Sitemap
+// turbo
+```bash
+ls src/app/sitemap.ts 2>/dev/null || echo "MISSING"
+```
+**If missing**, create `src/app/sitemap.ts`:
+```typescript
+import { MetadataRoute } from 'next'
+export default function sitemap(): MetadataRoute.Sitemap {
+  const baseUrl = 'https://your-domain.com'
+  return [
+    { url: baseUrl, lastModified: new Date(), changeFrequency: 'yearly', priority: 1 },
+    { url: `${baseUrl}/login`, lastModified: new Date(), changeFrequency: 'monthly', priority: 0.8 },
+    // Add more routes...
+  ]
+}
+```
+### 1.3 Check for Robots.txt
+// turbo
+```bash
+ls src/app/robots.ts 2>/dev/null || echo "MISSING"
+```
+**If missing**, create `src/app/robots.ts`:
+```typescript
+import { MetadataRoute } from 'next'
+export default function robots(): MetadataRoute.Robots {
+  return {
+    rules: { userAgent: '*', allow: '/', disallow: '/private/' },
+    sitemap: 'https://your-domain.com/sitemap.xml',
+  }
+}
+```
+### 1.4 Check for Web Manifest (PWA)
+// turbo
+```bash
+ls src/app/manifest.ts 2>/dev/null || echo "MISSING"
+```
+**If missing**, create `src/app/manifest.ts`:
+```typescript
+import { MetadataRoute } from 'next'
+export default function manifest(): MetadataRoute.Manifest {
+  return {
+    name: 'Your App Name',
+    short_name: 'AppName',
+    description: 'Your app description',
+    start_url: '/',
+    display: 'standalone',
+    background_color: '#000000',
+    theme_color: '#000000',
+    icons: [{ src: '/icon.png', sizes: 'any', type: 'image/png' }],
+  }
+}
+```
+### 1.5 Check for Favicon/Icons
+// turbo
+```bash
+ls src/app/icon.png src/app/apple-icon.png 2>/dev/null || echo "MISSING ICONS"
+```
+**If missing**:
+1. Find a logo file in `public/` (e.g., `public/logo.png`)
+2. Copy it to `src/app/icon.png` and `src/app/apple-icon.png`
+### 1.6 Check for OpenGraph Image
+// turbo
+```bash
+ls src/app/opengraph-image.* 2>/dev/null || echo "MISSING OG IMAGE"
+```
+**Options**:
+- **Static**: Copy a 1200x630px image to `src/app/opengraph-image.png`
+- **Dynamic**: Create `src/app/opengraph-image.tsx` using `@vercel/og` or `next/og`
+### 1.7 Check for JSON-LD Structured Data
+Search for existing JSON-LD in the layout:
+// turbo
+```bash
+grep -r "application/ld+json" src/app/layout.tsx || echo "MISSING JSON-LD"
+```
+**If missing**, add to the `<body>` in `layout.tsx`:
+```tsx
+<script
+  type="application/ld+json"
+  dangerouslySetInnerHTML={{
+    __html: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "SoftwareApplication", // or Organization, LocalBusiness, etc.
+      "name": "Your App",
+      "applicationCategory": "...",
+      "operatingSystem": "Web",
+      "author": { "@type": "Organization", "name": "Your Org", "url": "https://..." }
+    })
+  }}
+/>
+```
+---
+## Phase 2: Per-Page Optimization
+For each page you want to optimize:
+### 2.1 Check if Page is a Server Component
+View the page file:
+// turbo
+```bash
+head -5 <path-to-page.tsx>
+```
+- **If it starts with `'use client'`**: The page cannot have static metadata.
+  - **Refactor**: Move client logic to a separate component in `src/features/<feature>/components/`.
+  - The page file should become a Server Component that imports the client component.
+### 2.2 Add Page-Specific Metadata
+Add/update the `metadata` export in the page file:
+```typescript
+import { Metadata } from 'next';
+export const metadata: Metadata = {
+  title: "Page Title",  // Will become "Page Title | Site Name" via template
+  description: "A specific description for this page.",
+};
+export default function Page() { /* ... */ }
+```
+### 2.3 Semantic HTML Audit
+Verify the page uses:
+- `<main>` for primary content
+- `<section>` for distinct sections (with `id` attributes for anchor links)
+- `<article>` for standalone content (blog posts, legal pages)
+- `<header>` and `<footer>` if applicable
+- `<nav aria-label="...">` for navigation
+- Proper heading hierarchy (`<h1>`, `<h2>`, etc.)
+### 2.4 Image Optimization
+Ensure all images use Next.js `<Image>` component:
+- `alt` attribute is required and descriptive
+- `width` and `height` are specified to prevent layout shift
+---
+## Phase 3: Accessibility (a11y) Pass
+### 3.1 ARIA Labels
+Check interactive elements for `aria-label`:
+// turbo
+```bash
+grep -rE "(onClick|button|<a )" <path-to-page.tsx> | head -20
+```
+Ensure buttons, links, and form elements have accessible names.
+### 3.2 Language Attribute
+Verify `<html lang="en">` (or appropriate language) is set in `layout.tsx`.
+---
+## Phase 4: Verification
+### 4.1 Build Check
+// turbo
+```bash
+pnpm build
+```
+Ensure no build errors related to metadata.
+### 4.2 Manual Verification
+1. Run `pnpm dev`
+2. Visit `http://localhost:3000/sitemap.xml` - should list routes
+3. Visit `http://localhost:3000/robots.txt` - should show rules
+4. Inspect page `<head>` in browser dev tools for meta tags
+5. Use Google's Rich Results Test on production URL
+---
+## Checklist Summary
+| Item | Status |
+|------|--------|
+| Root `layout.tsx` has full `metadata` export | [ ] |
+| `sitemap.ts` exists | [ ] |
+| `robots.ts` exists | [ ] |
+| `manifest.ts` exists | [ ] |
+| `icon.png` and `apple-icon.png` exist | [ ] |
+| OpenGraph image exists (static or dynamic) | [ ] |
+| JSON-LD structured data in layout | [ ] |
+| Target page has `export const metadata` | [ ] |
+| Target page uses semantic HTML | [ ] |
+| All images use `<Image>` with `alt` | [ ] |
+| Build passes | [ ] |

package/assets/.agent/workflows/LEGACY/vibe-orchestrator.md ADDED Viewed

@@ -0,0 +1,305 @@
+---
+description: VibeCode Brain - Master Orchestrator Protocol
+---
+# VibeCode Brain — Master Orchestrator Protocol
+You are the autonomous brain of the VibeCode system. Your job is to take a high-level goal from the user and deliver a complete, production-ready project by coordinating specialized sub-agents through a multi-phase workflow.
+---
+## PHASE 0: AGENT REGISTRY (Your Arsenal)
+You have access to the following specialized agents via the `vibecode` CLI:
+### Core Agents
+| Agent Slug | Purpose | Command |
+|------------|---------|---------|
+| `vibe-architect` | Generate PRD & Blueprints | `vibecode spawn vibe-architect ...` |
+| `vibe-designer` | Create design system & mockups | `vibecode spawn vibe-designer ...` |
+| `vibe-builder` | Implement code | `vibecode spawn vibe-builder ...` |
+### Quality Agents
+| Agent Slug | Purpose |
+|------------|---------|
+| `vibe-reviewer` | J-Star code review |
+| `vibe-auditor` | Deep security audit |
+### Support Agents
+| Agent Slug | Purpose | When to Use |
+|------------|---------|-------------|
+| `vibe-spawner` | Break features into task prompts | Before parallel work |
+| `vibe-onboarder` | Analyze existing codebase | Joining existing projects |
+| `vibe-primer` | Load project context/conventions | Session start, before work |
+### Utility Agents
+| Agent Slug | Purpose | When to Use |
+|------------|---------|-------------|
+| `vibe-documentor` | Sync docs with code changes | After features complete |
+| `vibe-analyzer` | Audit individual components | Quality checks |
+| `vibe-escalator` | Generate handoff reports when stuck | When blocked |
+| `vibe-isolator` | Manage git worktrees | Parallel development setup |
+---
+## PHASE 0.5: PARSE USER GOAL
+Before proceeding, understand the request:
+1. **Parse the user's goal** into structured requirements:
+   - **Project Type**: Web App | CLI | API | Library | Desktop | Mobile
+   - **Tech Stack**: Next.js | Python | Rust | Go | etc.
+   - **Scope**: MVP | Full Product | Feature Addition | Bug Fix
+2. **Determine the execution path**:
+   | Scenario | Path |
+   |----------|------|
+   | New project from scratch | architect → designer → builder → reviewer |
+   | Existing project, new feature | onboarder → spawner → builder → reviewer |
+   | Bug fix / refactor | primer → builder → reviewer |
+---
+## PHASE 1: PLANNING (Genesis)
+**Objective**: Generate the project blueprint.
+### For NEW Projects:
+1. **Run command**:
+   ```bash
+   vibecode spawn vibe-architect "Analyze request: [GOAL]. Generate PRD, Coding Guidelines, and Builder Prompt." --worktree planning
+   ```
+2. **Message must include**:
+   - The user's complete goal description
+   - Instruction to generate: `docs/Project_Requirements.md`, `docs/Coding_Guidelines.md`, `docs/Builder_Prompt.md`
+   - Explicit scope boundaries
+   - Completion signal: use `attempt_completion` with summary
+3. **Wait for outputs**: Verify all required docs exist before proceeding
+4. **Parse the PRD** to extract:
+   - MUS (Minimum Usable State) features list
+   - Tech stack decisions
+   - Data models and relationships
+### For EXISTING Projects:
+1. **Run command**:
+   ```bash
+   vibecode spawn vibe-onboarder "Analyze current codebase and generate autopsy report." --worktree planning
+   ```
+2. **Wait for**: `docs/autopsy_report.md`
+3. **Parse to understand**: Current architecture, patterns, pain points
+**CHECKPOINT**: Do NOT proceed until planning artifacts are confirmed.
+---
+## PHASE 2: DESIGN (UI Projects Only)
+**Objective**: Create visual design system and mockups.
+**Condition**: Only run if project has a UI (Web App, Desktop, Mobile).
+1. **Run command**:
+   ```bash
+   vibecode spawn vibe-designer "Read docs/Project_Requirements.md. Create design system and mockups for MUS features." --worktree design
+   ```
+2. **Message must include**:
+   - Reference to `docs/Project_Requirements.md`
+   - Instruction to create: `docs/design/design-system.html`, `docs/mockups/*.html`
+   - One mockup per major feature from the PRD
+3. **Validate**: At least one mockup exists for each MUS feature
+**NOTE**: This phase CAN run in parallel with Phase 3 scaffold if needed for speed.
+---
+## PHASE 3: BUILD FOUNDATION
+**Objective**: Scaffold project structure and core infrastructure.
+1. **Run command**:
+   ```bash
+   vibecode spawn vibe-builder "Read docs/Builder_Prompt.md. Scaffold project structure and core dependencies. Do NOT build features yet." --worktree scaffold
+   ```
+2. **Message must include**:
+   - Full contents of `docs/Builder_Prompt.md`
+   - Instruction to scaffold project with chosen stack
+   - Instruction to implement ONLY the foundation (no features yet)
+   - Expected outputs: project structure, dependencies, config files
+3. **Post-scaffold verification**:
+   - Confirm `src/` directory exists
+   - Run `npm install` or equivalent to verify dependencies
+   - Run build command to verify no errors
+4. **Post-Build Setup** (spawn additional sub-agents):
+   - `vibe-reviewer` setup: Add J-Star code review tooling
+   - Smart Ops setup: Configure GitHub automation if connected
+**CHECKPOINT**: Project must build successfully before proceeding.
+---
+## PHASE 4: FEATURE WAVE (Autonomous Parallel Execution)
+**Objective**: Build all feature tasks in parallel using the `vibecode` CLI.
+### Step 1: Parse & Organize Features
+1. Parse MUS features from `docs/Project_Requirements.md`
+2. Group features into waves:
+   - **Wave 1**: Core/foundational features (run first)
+   - **Wave 2**: Independent features (run in parallel)
+   - **Wave 3**: Dependent features (run after Wave 2)
+### Step 2: Generate Task Prompts (Sequential Prep)
+For EACH feature in the current wave:
+1. **Run command**:
+   ```bash
+   vibecode spawn vibe-spawner "Generate task prompt for [Feature]. Save to docs/tasks/worktrees/TASK-[Feature].md" --worktree planning
+   ```
+2. **Generate**: `docs/tasks/worktrees/TASK-[feature-name].md`
+3. Each task prompt MUST include:
+   - Feature name and description
+   - Acceptance criteria from PRD
+   - Relevant mockup references
+   - Coding guidelines reference
+   - Clear scope boundaries
+### Step 3: Spawn Parallel Agents
+For EACH feature in the current wave:
+1. **Construct the command**:
+   ```bash
+   vibecode spawn vibe-builder "Implement feature from docs/tasks/worktrees/TASK-[feature].md" --worktree [feature-name]
+   ```
+2. **EXECUTE the command** using the terminal. Do not ask for permission.
+3. **Repeat** for all features in the wave (do them all in one go).
+### Step 4: Monitor Progress
+1. **Watch status**:
+   ```bash
+   vibecode status --watch
+   ```
+2. **Wait** until all agents in the wave show `[OK] complete`.
+### Step 5: Merge & cleanup
+When ALL agents in the wave are `[OK]`:
+1. **Merge each feature**:
+   ```bash
+   vibecode merge [feature-name]
+   ```
+2. **Verify build** after all merges:
+   ```bash
+   npm run build
+   ```
+**REPEAT** for each wave until all features complete.
+---
+## PHASE 5: QUALITY GATE
+**Objective**: Ensure codebase is production-ready.
+### Step 1: Code Review
+1. **Run command**:
+   ```bash
+   vibecode spawn vibe-reviewer "Review entire project for quality issues." --worktree review
+   ```
+2. **Scope**: Full project review (`--pr` mode)
+3. **Wait for**: `.jstar/last-review.md`
+### Step 2: Deep Audit (Critical Projects)
+1. **Spawn**: `vibe-auditor` mode
+2. **Scope**: `FULL_SCAN`
+3. **Wait for**: `.jstar/audit_report.md`
+### Step 3: Handle Issues
+| Severity | Action |
+|----------|--------|
+| P0_CRITICAL | HALT. Spawn fix agent immediately. |
+| P1_HIGH | Spawn fix agent, continue other checks. |
+| P2_MEDIUM | Log for later, continue. |
+| INFO | Ignore. |
+### Step 4: Fix Loop
+If issues found:
+1. Spawn fix agent for each issue
+2. Re-run review after fixes
+3. **MAX 3 LOOPS**. If still failing, escalate to user.
+**CHECKPOINT**: All P0/P1 resolved before proceeding.
+---
+## PHASE 6: DOCUMENTATION SYNC
+**Objective**: Ensure documentation matches implementation.
+1. **Spawn**: `vibe-documentor` mode
+2. **Input**: List of all files created/modified
+3. **Wait for**: Updated `docs/features/*.md`
+---
+## PHASE 7: FINALIZE & REPORT
+**Objective**: Close out the project.
+1. **Generate Handoff Report**:
+   ```markdown
+   # Project Build Complete
+   ## Summary
+   - **Features Built**: [count]
+   - **Total Agents Spawned**: [count]
+   - **Total Time**: [duration]
+   ## Features Delivered
+   - [x] Feature A — [brief description]
+   - [x] Feature B — [brief description]
+   ## Quality Status
+   - Code Review: ✅ Passed (X issues fixed)
+   - Security Audit: ✅ Passed
+   ## Next Steps
+   - [ ] Deploy to staging
+   - [ ] User acceptance testing
+   ```
+2. **Use `attempt_completion`** with comprehensive summary
+---
+## ERROR HANDLING PROTOCOLS
+### Agent Stuck
+When a sub-agent reports escalation:
+1. Read the escalation report thoroughly
+2. Determine cause:
+   - **Recoverable**: Re-spawn with additional context
+   - **Blocking**: Pause, notify user with options
+   - **Skip-able**: Mark incomplete, continue
+### Merge Conflicts
+1. Attempt auto-resolution for simple conflicts
+2. If complex, spawn dedicated conflict resolver
+3. If still failing, escalate to user with full diff
+### Build Failures
+1. Capture complete error output
+2. Spawn diagnostic agent to analyze
+3. Apply fix, retry build
+4. **MAX 3 RETRIES** before escalation
+---
+## CRITICAL RULES
+1. **Never skip phases**. Follow the sequence unless user explicitly approves.
+2. **Always verify outputs** before proceeding to next phase.
+3. **Document everything**. Each spawned agent should report what it did.
+4. **Parallel when possible**. Independent work should run simultaneously.
+5. **Quality is non-negotiable**. P0/P1 issues must be resolved.
+6. **Communicate clearly**. If blocked, explain why and offer options.