@draig/lexis-two 1.0.2 → 1.0.4

package/SPECXIS.md

@@ -1,576 +0,0 @@
-# Specxis — Implementation Guide
-
-> Spec-driven development layer for Lexis-Two.
-> Inspired by OpenSpec and GitHub Spec Kit, built for the Lexis philosophy.
-> Implement this guide in the `nitdraig/lexis-two` repository.
-
----
-
-## Overview
-
-Specxis adds a lightweight SDD (Spec-Driven Development) layer to Lexis-Two.
-It persists agreements between developer and agent as Markdown files in the
-repo, so context survives across sessions and chat resets.
-
-The lazy hierarchy still applies first. Specxis only activates when a feature
-is complex enough to warrant it.
-
----
-
-## When to use Specxis
-
-**Use it for:**
-- Features touching 3+ files
-- Anything requiring UX + backend coordination
-- Ambiguous requirements that need alignment before coding
-
-**Skip it for:**
-- Bug fixes with a clear root cause
-- Style or naming changes
-- Adding tests to existing behavior
-- Single-file changes with obvious scope
-
----
-
-## Folder Convention (per project)
-
-Create this structure in any project that uses Specxis:
-
-```
-.specxis/
-  active/
-    [feature-slug]/
-      proposal.md    ← what to build and why (lazy check included)
-      spec.md        ← requirements as MUST / SHOULD / MAY
-      tasks.md       ← task list generated by /specxis-plan
-      review.md      ← lexis-review findings (added on close)
-  archive/
-    [feature-slug]/  ← completed specs, immutable
-  debt.md            ← consolidated // lexis: comments for this project
-```
-
----
-
-## Files to Create
-
-### 1. `templates/specxis/proposal.md`
-
-```markdown
-# Proposal: [feature-slug]
-
-## Goal
-One sentence — what does this feature do for the user?
-
-## Lazy Check
-Answer before writing any code:
-- Does this need to exist? Could the requirement be met another way?
-- Does stdlib, the framework, or an installed dep already cover it?
-- What is the absolute minimum that satisfies the requirement?
-
-## Context
-- Affected domain / feature folder:
-- Related existing files:
-- Dependencies already installed that are relevant:
-
-## Out of Scope (YAGNI)
-Explicitly list what this proposal does NOT include.
-
-## Open Questions
-Anything that needs clarification before planning.
-```
-
-### 2. `templates/specxis/spec.md`
-
-```markdown
-# Spec: [feature-slug]
-
-> Status: draft | agreed | implementing | done
-
-## Requirements
-
-### MUST (non-negotiable)
-- [ ] 
-
-### SHOULD (strong preference, can deviate with // lexis: comment)
-- [ ] 
-
-### MAY (optional, implement only if trivial)
-- [ ] 
-
-## Constraints
-- Performance:
-- Security:
-- Accessibility:
-- TypeScript: strict — no any, as, or ! without // lexis: explanation
-
-## Acceptance Criteria
-How do we know this is done?
-- [ ] 
-```
-
-### 3. `templates/specxis/tasks.md`
-
-```markdown
-# Tasks: [feature-slug]
-
-> Generated by /specxis-plan. Each task maps to one file or one function.
-> Do not start implementing until tasks are agreed.
-
-## Tasks
-
-- [ ] task-001: 
-- [ ] task-002: 
-- [ ] task-003: 
-
-## Implementation Notes
-Decisions made during planning that affect implementation.
-
-## Lexis Tags Added
-// lexis: comments added during implementation (updated as work progresses).
-```
-
-### 4. `templates/specxis/review.md`
-
-```markdown
-# Review: [feature-slug]
-
-> Generated by /specxis-review on close.
-
-## Summary
-One sentence on overall quality.
-
-## Spec Compliance
-Did the implementation follow spec.md?
-- MUST requirements met: yes / no / partial
-- Deviations: list with // lexis: references
-
-## Debt Registered
-// lexis: comments added during this feature — moved to .specxis/debt.md.
-
-## Next Steps
-Recommended follow-up actions in priority order.
-```
-
----
-
-## Commands to Create
-
-All commands go in `.opencode/command/` (OpenCode) and `commands/` (Gemini CLI `.toml`).
-
-### `.opencode/command/specxis-new.md`
-
-```markdown
----
-description: "Create a new Specxis spec folder for a feature"
----
-
-Create the folder structure for a new spec.
-
-Steps:
-1. Ask for the feature slug if not provided (kebab-case, e.g. "user-auth")
-2. Create `.specxis/active/[slug]/proposal.md` from `templates/specxis/proposal.md`
-3. Apply the lazy check inline: ask "Does this need to exist? What's the minimum?"
-4. Fill in what you know from the user's description — leave unknowns blank
-5. Report the created path and ask the user to review the proposal before planning
-
-Do not create spec.md or tasks.md yet — those come after proposal is agreed.
-Respond in Spanish.
-```
-
-### `.opencode/command/specxis-plan.md`
-
-```markdown
----
-description: "Read the active proposal and generate a task list using the lazy hierarchy"
----
-
-Read `.specxis/active/[slug]/proposal.md` (ask for slug if multiple are active).
-
-Apply the lazy hierarchy to every proposed piece:
-1. Does this need to exist? → rule it out if not
-2. Stdlib/native? → use it
-3. Existing dep? → use it
-4. One line? → make it one line
-5. Only then: minimum build
-
-Then:
-1. Create `.specxis/active/[slug]/spec.md` from `templates/specxis/spec.md`
-   - Fill MUST / SHOULD / MAY from the proposal
-2. Create `.specxis/active/[slug]/tasks.md` from `templates/specxis/tasks.md`
-   - Each task maps to exactly one file or one function
-   - Maximum 10 tasks — if more are needed, split into sub-specs
-3. Report the task list and ask for approval before any implementation starts
-
-Do not write any application code. Plan only.
-Respond in Spanish.
-```
-
-### `.opencode/command/specxis-implement.md`
-
-```markdown
----
-description: "Implement the next unchecked task in the active spec"
----
-
-Read `.specxis/active/[slug]/tasks.md` (ask for slug if multiple are active).
-
-Find the first unchecked task (`- [ ]`).
-
-Implement it following:
-- spec.md MUST requirements strictly
-- AGENTS.md rules (SOLID, KISS, no any/as/!, etc.)
-- Lazy hierarchy — stop at the simplest solution that satisfies the spec
-
-Mark the task as done (`- [x]`) in tasks.md after implementation.
-Add `// lexis:` comments for any deviation from spec.md or any intentional simplification.
-Update the "Lexis Tags Added" section in tasks.md.
-
-Implement one task per run. Stop and report before moving to the next.
-Respond in Spanish.
-```
-
-### `.opencode/command/specxis-review.md`
-
-```markdown
----
-description: "Review implementation against the active spec and AGENTS.md"
----
-
-Read `.specxis/active/[slug]/spec.md` and run `git diff HEAD`.
-
-Evaluate:
-1. **Spec compliance**: Are all MUST requirements met? List any gaps.
-2. **SHOULD compliance**: Are deviations explained with // lexis: comments?
-3. **AGENTS.md compliance**: SOLID, KISS, no any/as/!, loading/error/empty states
-4. **Lazy check**: Anything added that wasn't in the spec? Anything that could be simpler?
-5. **Tests**: New behavior covered by tests?
-
-Write findings to `.specxis/active/[slug]/review.md`.
-
-Format per finding:
-- Severity: Critical / High / Medium / Low
-- Location: file:line
-- Issue and recommended fix
-
-If the implementation is clean, say so directly — don't invent problems.
-Respond in Spanish.
-```
-
-### `.opencode/command/specxis-close.md`
-
-```markdown
----
-description: "Close a completed spec — archive it and sync debt"
----
-
-Close the spec at `.specxis/active/[slug]/`.
-
-Steps:
-1. Verify all tasks in tasks.md are checked (`- [x]`)
-2. Verify review.md exists and has no Critical or High findings open
-3. Move `.specxis/active/[slug]/` to `.specxis/archive/[slug]/`
-4. Collect all `// lexis:` comments added during this feature
-5. Append them to `.specxis/debt.md` under a `## [slug] — [date]` heading
-6. Report what was archived and what debt was registered
-
-If unchecked tasks or open Critical/High findings exist: refuse to close and list what's blocking.
-Respond in Spanish.
-```
-
-### `.opencode/command/specxis-debt.md`
-
-```markdown
----
-description: "Sync all // lexis: comments from the codebase to .specxis/debt.md"
----
-
-Scan the entire codebase for `// lexis:` comments:
-
-```bash
-grep -rn "lexis:" src --include="*.ts" --include="*.tsx" --include="*.js" --include="*.mjs"
-```
-
-Compare against `.specxis/debt.md`:
-- Add any comments not yet registered
-- Mark as "resolved" any that no longer exist in the code
-
-Produce a prioritized ledger:
-- **Immediate**: shortcuts causing pain or blocking features
-- **Next sprint**: shortcuts with a known ceiling approaching
-- **Backlog**: fine for now, revisit at scale
-- **Permanent**: intentional, no action needed
-
-Update `.specxis/debt.md` in place.
-Respond in Spanish.
-```
-
-### `.opencode/command/specxis.md`
-
-```markdown
----
-description: "Show active specs and their status"
----
-
-List all folders in `.specxis/active/`.
-
-For each, show:
-- Feature slug
-- Status from spec.md (draft / agreed / implementing / done)
-- Tasks: X/Y checked
-- Has review.md: yes / no
-
-Then list count of archived specs in `.specxis/archive/`.
-Show open items in `.specxis/debt.md` by priority.
-
-If `.specxis/` does not exist: suggest running `node scripts/specxis-init.js`.
-Respond in Spanish.
-```
-
----
-
-## Script to Create
-
-### `scripts/specxis-init.js`
-
-```javascript
-// scripts/specxis-init.js
-// Initializes .specxis/ folder structure in the current project.
-// Run with: node scripts/specxis-init.js
-
-import fs from 'fs';
-import path from 'path';
-
-const dirs = [
-  '.specxis/active',
-  '.specxis/archive',
-];
-
-const debtTemplate = `# Specxis Debt Ledger
-
-Consolidated // lexis: comments across all features.
-Updated automatically by /specxis-debt and /specxis-close.
-
----
-
-<!-- Entries added by specxis-close and specxis-debt commands -->
-`;
-
-for (const dir of dirs) {
-  fs.mkdirSync(dir, { recursive: true });
-  console.log(`created ${dir}/`);
-}
-
-const debtPath = '.specxis/debt.md';
-if (!fs.existsSync(debtPath)) {
-  fs.writeFileSync(debtPath, debtTemplate);
-  console.log(`created ${debtPath}`);
-}
-
-// Add .specxis/archive to .gitignore if not already there
-// (active specs stay in git; archive is optional)
-const gitignorePath = '.gitignore';
-if (fs.existsSync(gitignorePath)) {
-  const content = fs.readFileSync(gitignorePath, 'utf8');
-  if (!content.includes('.specxis/archive')) {
-    fs.appendFileSync(gitignorePath, '\n# Specxis archived specs (optional)\n# .specxis/archive\n');
-    console.log('added .specxis/archive comment to .gitignore');
-  }
-}
-
-console.log('\nSpecxis initialized. Run /specxis-new to create your first spec.');
-```
-
----
-
-## Skills to Create
-
-### `skills/specxis/SKILL.md`
-
-```markdown
----
-name: specxis
-description: Activate spec-driven development mode — align on requirements before writing any code
----
-
-You are now in Specxis mode. Before writing any code:
-
-1. Check if `.specxis/active/` exists and has an open spec for this feature
-2. If yes: read proposal.md and spec.md — follow them strictly
-3. If no: suggest running /specxis-new for complex features (3+ files)
-4. Apply the lazy hierarchy to every requirement before accepting it into the spec
-5. Never implement beyond what spec.md defines (YAGNI)
-6. Mark every deviation with // lexis: and update tasks.md
-
-The spec is the contract. The code is the proof.
-Respond in Spanish. All code, comments, JSDoc in English.
-```
-
-### `skills/specxis-plan/SKILL.md`
-
-```markdown
----
-name: specxis-plan
-description: Generate a task list from a Specxis proposal using the lazy decision hierarchy
----
-
-Read `.specxis/active/[slug]/proposal.md`.
-
-Apply the lazy hierarchy to every proposed piece before accepting it into the plan.
-Generate spec.md (MUST/SHOULD/MAY) and tasks.md (one task per file or function, max 10).
-
-Do not write any application code. Plan only.
-Ask for approval before implementation starts.
-Respond in Spanish.
-```
-
-### `skills/specxis-review/SKILL.md`
-
-```markdown
----
-name: specxis-review
-description: Review implementation against the active Specxis spec and AGENTS.md rules
----
-
-Read `.specxis/active/[slug]/spec.md` and the current git diff.
-
-Evaluate spec compliance (MUST/SHOULD), AGENTS.md compliance, and lazy check.
-Write findings to `.specxis/active/[slug]/review.md`.
-
-Never modify application code. Read-only analysis only.
-Respond in Spanish.
-```
-
----
-
-## Gemini CLI Commands to Create
-
-For each `.opencode/command/*.md` above, create a matching `.toml` in `commands/`:
-
-```toml
-# commands/specxis-new.toml
-name = "specxis-new"
-description = "Create a new Specxis spec folder for a feature"
-skill = "../skills/specxis/SKILL.md"
-```
-
-Repeat for: `specxis-plan`, `specxis-implement`, `specxis-review`, `specxis-close`, `specxis-debt`, `specxis`.
-
----
-
-## docs/specxis.md to Create
-
-```markdown
-# Specxis — Spec-Driven Development for Lexis
-
-Specxis is the lightweight SDD layer built into Lexis-Two.
-Inspired by OpenSpec and GitHub Spec Kit, adapted to the Lexis philosophy.
-
-## When to use
-
-| Situation | Use Specxis? |
-|-----------|-------------|
-| Feature touching 3+ files | Yes |
-| UX + backend coordination | Yes |
-| Ambiguous requirements | Yes |
-| Bug fix with clear cause | No |
-| Style or naming change | No |
-| Adding tests to existing code | No |
-
-## Workflow
-
-```
-/specxis-new    → proposal.md (lazy check first)
-/specxis-plan   → spec.md + tasks.md
-/specxis-implement → one task at a time
-/specxis-review → review.md
-/specxis-close  → archive + debt sync
-```
-
-## Key principle
-
-The lazy hierarchy applies to the spec itself.
-Before adding a requirement to spec.md, ask: does it need to exist?
-A good spec is short. A great spec is shorter.
-
-## Integration with Lexis-One
-
-When .specxis/active/ exists, Lexis-One reads it automatically.
-No configuration needed — the folder is the signal.
-```
-
----
-
-## Roadmap Entry to Add
-
-Add this to `README.md` after v0.4:
-
-```markdown
-### v0.5 — Specxis (Spec-Driven Development)
-
-Lightweight SDD layer for complex features — inspired by OpenSpec and Spec Kit,
-built for the Lexis philosophy: lazy check before every requirement.
-
-- [ ] `.specxis/` folder convention and `scripts/specxis-init.js`
-- [ ] Commands: `specxis`, `specxis-new`, `specxis-plan`, `specxis-implement`,
-      `specxis-review`, `specxis-close`, `specxis-debt`
-- [ ] Skills: `specxis`, `specxis-plan`, `specxis-review`
-- [ ] Templates: `templates/specxis/proposal.md`, `spec.md`, `tasks.md`, `review.md`
-- [ ] `docs/specxis.md` — when to use SDD vs direct implementation
-- [ ] Gemini CLI commands (`.toml`) for all Specxis commands
-- [ ] Integration guide for Lexis-One private config
-```
-
----
-
-## Summary of Files to Create
-
-```
-templates/
-  specxis/
-    proposal.md
-    spec.md
-    tasks.md
-    review.md
-
-.opencode/command/
-  specxis.md
-  specxis-new.md
-  specxis-plan.md
-  specxis-implement.md
-  specxis-review.md
-  specxis-close.md
-  specxis-debt.md
-
-commands/
-  specxis.toml
-  specxis-new.toml
-  specxis-plan.toml
-  specxis-implement.toml
-  specxis-review.toml
-  specxis-close.toml
-  specxis-debt.toml
-
-skills/
-  specxis/SKILL.md
-  specxis-plan/SKILL.md
-  specxis-review/SKILL.md
-
-scripts/
-  specxis-init.js
-
-docs/
-  specxis.md
-
-README.md  ← add v0.5 entry to roadmap
-```
-
----
-
-## Notes for the Agent
-
-- All user-facing output in Spanish. All code, comments, file content in English.
-- Follow AGENTS.md strictly — no abstractions not listed here, no extra deps.
-- `specxis-init.js` uses ESM (`import`) — check `package.json` for `"type": "module"` before writing.
-- The `.specxis/` folder goes in the **project using Lexis-Two**, not in the lexis-two repo itself.
-  The lexis-two repo only holds the templates, commands, skills, and scripts.
-- Run `node scripts/check-rule-copies.js` after creating new skills to verify sync.

package/assets/benchmark-3model.svg

@@ -1,21 +0,0 @@
-<svg viewBox="0 0 860 336" xmlns="http://www.w3.org/2000/svg" font-family="-apple-system, 'Segoe UI', Helvetica, Arial, sans-serif">
-  <title>Median lines of code per arm across three models</title>
-  <text x="20" y="26" font-size="15" font-weight="600" fill="#8b949e">Median lines of code. 10 runs per cell. Lower is leaner.</text>
-  <text x="20" y="45" font-size="12" fill="#8b949e" opacity="0.85">Ponytail writes 80-94% less code, costs 47-77% less, and runs 3-6x faster than a no-skill agent.</text>
-  <rect x="20" y="58" width="12" height="12" rx="2" fill="#8b949e"/><text x="38" y="69" font-size="13" fill="#8b949e">baseline (no skill)</text>
-  <rect x="190" y="58" width="12" height="12" rx="2" fill="#d9822b"/><text x="208" y="69" font-size="13" fill="#8b949e">caveman</text>
-  <rect x="300" y="58" width="12" height="12" rx="2" fill="#2da44e"/><text x="318" y="69" font-size="13" fill="#8b949e">ponytail</text>
-  <text x="112" y="119" font-size="13" font-weight="600" fill="#8b949e" text-anchor="end">Haiku</text>
-  <rect x="120" y="92" width="508" height="14" rx="2" fill="#8b949e"/><text x="634" y="103" font-size="11" fill="#8b949e">518</text>
-  <rect x="120" y="110" width="114" height="14" rx="2" fill="#d9822b"/><text x="240" y="121" font-size="11" fill="#d9822b">116</text>
-  <rect x="120" y="128" width="38" height="14" rx="2" fill="#2da44e"/><text x="164" y="139" font-size="11" fill="#2da44e" font-weight="600">39</text>
-  <text x="112" y="193" font-size="13" font-weight="600" fill="#8b949e" text-anchor="end">Sonnet</text>
-  <rect x="120" y="166" width="680" height="14" rx="2" fill="#8b949e"/><text x="806" y="177" font-size="11" fill="#8b949e">693</text>
-  <rect x="120" y="184" width="118" height="14" rx="2" fill="#d9822b"/><text x="244" y="195" font-size="11" fill="#d9822b">120</text>
-  <rect x="120" y="202" width="43" height="14" rx="2" fill="#2da44e"/><text x="169" y="213" font-size="11" fill="#2da44e" font-weight="600">44</text>
-  <text x="112" y="267" font-size="13" font-weight="600" fill="#8b949e" text-anchor="end">Opus</text>
-  <rect x="120" y="240" width="251" height="14" rx="2" fill="#8b949e"/><text x="377" y="251" font-size="11" fill="#8b949e">256</text>
-  <rect x="120" y="258" width="66" height="14" rx="2" fill="#d9822b"/><text x="192" y="269" font-size="11" fill="#d9822b">67</text>
-  <rect x="120" y="276" width="50" height="14" rx="2" fill="#2da44e"/><text x="176" y="287" font-size="11" fill="#2da44e" font-weight="600">51</text>
-  <text x="120" y="324" font-size="11" fill="#8b949e" opacity="0.8">Median of 10 runs/cell, default temperature. 5 tasks (email, debounce, CSV sum, countdown, rate-limit), same model per group. Reproduce: npx promptfoo eval -c benchmarks/promptfooconfig.yaml</text>
-</svg>