@pasko70/pibo 1.1.0 → 1.3.0

package/skills/builtin/pibo-docker-system/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: pibo-docker-system
+description: Use this skill for Pibo Docker Compute System work, isolated implementation, worker worktrees, Chat Web or gateway testing, worker dev auth, browser/CDP validation, resource cleanup, and when coordinating Docker worker use with the github-server-flow strategy.
+---
+
+# Pibo Docker Compute System
+
+Use Docker compute workers as the isolated execution boundary for Pibo code work, gateway checks, Chat Web validation, browser automation, and end-to-end tests. Keep Docker-specific operating rules here instead of duplicating them in `AGENTS.md`.
+
+## Relationship to GitHub flow
+
+Use this skill together with `github-server-flow`:
+
+- `github-server-flow` owns branch, PR, fork mirror, and release strategy.
+- `pibo-docker-system` owns where implementation and validation run.
+- Normal code work starts from `upstream/dev` on a focused branch, then runs inside a Docker dev worker.
+- Do not use `origin/dev` as a preview or staging branch just to test work. Push focused branches to `origin` and open PRs to `upstream/dev`.
+- Documentation-only edits do not require a Docker worker unless they are coupled to code, build, gateway, or browser validation.
+
+### Worker branch pattern
+
+`pibo compute dev spawn --worktree <name>` creates or attaches a Git worktree and uses `<name>` as the local branch name. Because container names and worktree names should be simple, prefer a slash-free local worker branch and push it to a slash-based PR branch when ready.
+
+Recommended pattern:
+
+```bash
+cd /root/code/pibo
+git fetch origin --prune
+git fetch upstream --prune
+
+# Use a slash-free local branch/worktree name created from upstream/dev.
+git branch <short-topic> upstream/dev
+pibo compute dev spawn --worktree <short-topic>
+
+# Work in the returned worktree, then push as a focused PR branch.
+cd /root/code/pibo/.worktrees/<short-topic>
+git push -u origin HEAD:feature/<short-topic>
+```
+
+If the local branch already exists and points at the intended base, `pibo compute dev spawn --worktree <short-topic>` attaches a worktree for it. If it does not exist, the compute CLI creates it from the current checkout, so pre-create the branch from `upstream/dev` when strict upstream-first history matters.
+
+## Commands
+
+Discover progressively with the CLI first:
+
+```bash
+pibo compute --help
+pibo compute dev --help
+pibo compute dev spawn --help
+```
+
+Common commands:
+
+- `pibo compute spawn [--name <name>]` — create a short-lived worker container. It is useful for isolated checks but does not create the development worktree flow.
+- `pibo compute dev spawn --worktree <name>` — create a long-lived dev worker with a Git worktree and deterministic port block.
+- `pibo compute rebuild` — force a fresh Docker image build.
+- `pibo compute list` / `pibo compute list --all` — inspect worker and dev-worker containers.
+- `pibo compute release <id>` — stop and remove the named worker container. This does not delete the Git worktree.
+- `pibo compute reap --dry-run` — preview worker cleanup.
+- `pibo compute reap --apply` — apply selected cleanup. Dev workers are excluded unless the command explicitly includes them.
+- `pibo compute health` / `pibo compute doctor` — read-only resource health checks.
+- `pibo compute diagnostics` / `pibo compute disk` — read-only Docker disk diagnostics.
+
+## Development rule
+
+Use a Docker dev worker for Pibo code and feature implementation whenever the compute system is available, especially for:
+
+- gateway changes;
+- Chat Web changes;
+- browser automation;
+- auth behavior;
+- runtime/session routing changes;
+- CLI/TUI changes that need realistic user-visible validation;
+- end-to-end checks.
+
+Do not edit the host checkout as an experimental workspace for code changes. Do not restart, replace, or run ad hoc host gateways for development unless the user explicitly requests host operations or Docker is unavailable. The host gateway is for observation and production/dev deployment only.
+
+## Worker lifecycle
+
+1. Start from the GitHub strategy: fetch remotes, create a focused branch from `upstream/dev`, and spawn a dev worker for that branch.
+2. Use the returned worktree for edits.
+3. Use the returned web and CDP ports for app and browser checks.
+4. Run builds/tests inside the worker worktree when the work requires runtime validation.
+5. Release the container with `pibo compute release <id>` when done.
+6. Keep, merge, push, or discard the Git worktree only after review or explicit user approval.
+
+Releasing a dev worker removes the container, not the worktree. Worktree deletion is a separate Git cleanup decision.
+
+## Gateway and deployment boundaries
+
+Host gateways are managed only through the Pibo CLI:
+
+```bash
+pibo gateway web status
+pibo gateway web start
+pibo gateway web restart
+pibo gateway dev status
+pibo gateway dev start
+pibo gateway dev restart
+```
+
+After Docker validation, use the host dev gateway for host-level testing:
+
+```bash
+./scripts/deploy-web-dev.sh
+pibo gateway dev restart
+```
+
+The hosted dev Chat URL is host-specific. Set `PIBO_DEV_PUBLIC_URL` or `PIBO_DEV_BASE_URL` in the environment or repo-local `.env.developer-host`; do not hard-code public hostnames in docs, scripts, or skills.
+
+Deploy production only after dev testing succeeds and the user approves it:
+
+```bash
+./scripts/deploy-web.sh
+pibo gateway web restart
+```
+
+If the production gateway restart is blocked because active agent work is running, ask the user before interrupting sessions. Do not bypass the CLI restart guard without explicit confirmation.
+
+## Dev auth boundary
+
+Dev auth belongs only to Docker workers.
+
+- `gateway:web` inside a worker enables dev auth through the Docker entrypoint's internal option.
+- `PIBO_DEV_AUTH` does not enable dev auth for normal host gateways.
+- Never start the host gateway with dev-auth flags or fake-auth infrastructure.
+- The normal host gateway must use Better Auth.
+- Dev-auth web access is loopback-only; if a worker web port is accidentally reached through a public reverse proxy, auth requests are rejected.
+
+If auth is needed inside a Docker worker, use the `pibo-debug-auth` skill rather than bypassing auth ad hoc.
+
+## Browser and app validation
+
+For Chat Web browser debugging while changing Pibo, start from the Docker dev worker when one is available. Use the worker's returned web/CDP ports so browser automation and gateway restarts stay isolated from host gateways.
+
+Useful validation evidence includes:
+
+- route visited;
+- visible state or DOM assertions;
+- screenshot path;
+- CDP target details;
+- request/response evidence;
+- terminal output for CLI/TUI flows.
+
+A gateway healthcheck only proves the service responds. For Web, CLI, TUI, gateway, runtime, auth, or agent-routing work, also verify user-visible behavior when feasible:
+
+- Use browser/CDP or browser-use for Web UI flows.
+- Use a pseudo-TTY or interactive shell for Ink/TUI flows.
+- Use the real command, API, router, or persistence path when the default path is locally testable.
+
+Fake/demo checks and healthchecks are useful supporting evidence, but do not treat them as final validation for a user-facing default path unless the real path is unavailable or explicitly out of scope.
+
+## Resource hygiene
+
+- Workers are intended to be bounded and recyclable.
+- Prefer `pibo compute release <id>` when you finish with a worker.
+- Use `pibo compute list --all` to inspect running, stopped, dirty, and OOM-killed workers.
+- Use `pibo compute reap --dry-run` before destructive cleanup.
+- Use `pibo compute health` and `pibo compute diagnostics --json` for read-only resource investigations.
+- Do not delete worktrees just because containers were released. Worktree cleanup must be explicit.
+
+## Source docs
+
+For exact product requirements and implementation details, read the canonical docs on demand:
+
+- `docs/specs/capabilities/docker-compute-workers.md`
+- `docs/specs/capabilities/standalone-docker-runtime.md`
+- `docs/project/compute-browser-resource-operating-model.md`
+- `docs/project/compute-browser-resource-rollout-checklist.md`
+- `src/skills/pibo-debug-auth/SKILL.md`

package/skills/builtin/pibo-spec-writing/SKILL.md

@@ -0,0 +1,330 @@
+---
+name: pibo-spec-writing
+description: Defines how Pibo specs are written, structured, reviewed, and split into proposals, capability specs, phase specs, designs, and tasks. Use this whenever the user asks to create, review, rewrite, compare, or implement a spec; mentions requirements, acceptance criteria, scope, roadmap, proposal, design plan, tasks, OpenSpec, Spec Kit, GSD, or spec-driven development; or asks where project documentation should live.
+---
+
+# Pibo Spec Writing
+
+Use this skill when creating or reviewing specs for Pibo. A good Pibo spec is behavior-first, scoped, testable, concise, and traceable to implementation work. Keep implementation details out of the spec unless they are externally visible constraints.
+
+## Core principles
+
+Write specs so another agent can implement and verify the work without reading the original chat.
+
+1. Start with why the change matters.
+2. Define the observable behavior, not the code shape.
+3. Bound the scope with clear in-scope and out-of-scope lists.
+4. Make every requirement testable.
+5. Add scenarios or acceptance criteria for each important behavior.
+6. Track assumptions and open questions instead of hiding them.
+7. Link requirements to phases, tasks, or plans when the work is large.
+8. Use clear prose: active voice, concrete words, short paragraphs, and no puffery.
+9. For user-facing UI, CLI, TUI, gateway, runtime, or agent-routing changes, name the expected verification level instead of assuming unit tests are enough.
+
+## Where specs live
+
+Follow the project documentation structure:
+
+```text
+docs/
+  project/  Current project docs and canonical documentation
+  specs/    Product, technical, and implementation specifications
+  plans/    Implementation plans and design plans
+  reports/  Investigation, validation, and generated reports
+  legacy/   Old documentation kept for reference
+```
+
+Do not create new root-level `plans/`, `reports/`, or `specs/` directories.
+
+Use `docs/specs/` for durable specs. Use `docs/plans/` for implementation plans. Use `docs/reports/` for analyses, validations, and findings.
+
+## Choose the right spec shape
+
+### Capability spec
+
+Use a capability spec for durable system behavior, especially behavior that should remain true after the current change ships.
+
+Good path:
+
+```text
+docs/specs/capabilities/<capability-name>.md
+```
+
+Use this for auth behavior, session routing, profile behavior, tool registration, gateway contracts, API behavior, UI behavior, or other long-lived contracts.
+
+### Change spec
+
+Use a change spec when proposing a feature, fix, or migration.
+
+Good path:
+
+```text
+docs/specs/changes/<change-name>/
+  proposal.md
+  spec.md
+  design.md       # include when technical choices matter
+  tasks.md        # include when ready to implement
+```
+
+### Phase spec
+
+Use a phase spec for multi-step work that needs a roadmap.
+
+Good path:
+
+```text
+docs/specs/phases/<NN-phase-name>/
+  spec.md
+  context.md      # implementation decisions, references, existing-code notes
+```
+
+## Required structure for most Pibo specs
+
+Use this template unless the task clearly needs a smaller artifact.
+
+```markdown
+# Spec: [Name]
+
+**Status:** Draft | Approved | Implementing | Done
+**Created:** YYYY-MM-DD
+**Requester / Source:** [user, issue, discussion, or change]
+**Related docs:** [links]
+
+## Why
+
+[Problem, opportunity, or user need. One or two concrete paragraphs.]
+
+## Goal
+
+[One precise sentence that says what changes from current state to target state.]
+
+## Background / Current State
+
+[What exists today. What is broken, missing, confusing, slow, unsafe, or expensive.]
+
+## Scope
+
+### In Scope
+
+- [Concrete behavior or deliverable]
+
+### Out of Scope
+
+- [Excluded item] — [reason]
+
+## Requirements
+
+### Requirement: [Name]
+
+The system MUST/SHALL [observable behavior].
+
+#### Current
+
+[Current behavior or absence of behavior.]
+
+#### Target
+
+[Desired behavior.]
+
+#### Acceptance
+
+[Concrete pass/fail check.]
+
+#### Scenario: [Name]
+
+- GIVEN [state]
+- WHEN [action/event]
+- THEN [expected outcome]
+
+## Edge Cases
+
+- [Boundary, failure, permission, concurrency, or empty-state case]
+
+## Constraints
+
+- **Compatibility:** ...
+- **Security / Privacy:** ...
+- **Performance:** ...
+- **Dependencies:** ...
+
+## Success Criteria
+
+- [ ] SC-001: [Measurable or directly observable outcome]
+- [ ] SC-002: [Another pass/fail outcome]
+
+## Assumptions and Open Questions
+
+### Assumptions
+
+- [Reasonable default taken to keep progress moving]
+
+### Open Questions
+
+- [Question that materially affects scope, UX, security, or architecture]
+
+## Traceability
+
+| Requirement | Scenario / Story | Plan / Task | Status |
+|---|---|---|---|
+| REQ-001 | [Scenario] | [Plan or task] | Pending |
+```
+
+## Minimal spec
+
+For small work, use the shortest form that remains testable:
+
+```markdown
+# Spec: [Name]
+
+## Why
+## Goal
+## Scope
+### In Scope
+### Out of Scope
+## Requirements
+## Acceptance Criteria
+## Assumptions / Open Questions
+```
+
+Use the full template when the change touches multiple modules, changes public behavior, affects auth/security/data, or will be implemented across multiple sessions.
+
+## Requirement rules
+
+Write requirements as behavior contracts.
+
+Good:
+
+```markdown
+### Requirement: Dev gateway status is discoverable
+
+The CLI MUST show whether the dev gateway is running, its PID when known, and the command to inspect logs.
+
+#### Scenario: Gateway is running
+- GIVEN the dev gateway process is active
+- WHEN an operator runs `pibo gateway dev status`
+- THEN the output includes status, PID, port, and next diagnostic command
+```
+
+Weak:
+
+```markdown
+### Requirement: Improve gateway status
+Make gateway status better and more robust.
+```
+
+A requirement is ready when a reviewer can say pass or fail without guessing.
+
+## Reuse, parity, and verification clarity
+
+When a feature is described as "same as Web", "derived from Web", "reuse the view", "shared UI", "Terminal View", or similar, do not silently reduce that to shared data. State the intended reuse level:
+
+- data/state only
+- renderer-neutral view model
+- interaction/controller logic
+- renderer/component logic
+- visual and behavioral parity
+
+If visual or behavioral parity is required, add acceptance checks that compare the relevant surfaces with the same fixture or user flow. If parity is intentionally out of scope, say so and describe the user-visible difference.
+
+For user-facing UI, CLI, TUI, gateway, runtime, auth, or agent-routing specs, include at least one realistic validation scenario for the default user path when feasible. Fake data, demo mode, mocks, and render snapshots are useful, but they should not be the only acceptance evidence for behavior users will exercise directly unless the real path is unavailable or explicitly out of scope.
+
+## Scenario rules
+
+Prefer GIVEN / WHEN / THEN for user-visible behavior and system contracts. Use WHEN / THEN only for simple event-response behavior.
+
+Cover at least:
+
+- primary success path
+- empty or missing state
+- invalid input or permission failure
+- migration or compatibility path when relevant
+
+## Proposal structure
+
+Use `proposal.md` to explain intent before deep design.
+
+```markdown
+# Proposal: [Change]
+
+## Why
+
+## What Changes
+
+## Capabilities
+
+### New Capabilities
+- `<kebab-name>`: [brief behavior area]
+
+### Modified Capabilities
+- `<existing-name>`: [changed behavior]
+
+## Impact
+
+- **Code:** ...
+- **APIs / CLI:** ...
+- **Data:** ...
+- **Auth / Security:** ...
+- **Docs:** ...
+```
+
+## Design structure
+
+Use `design.md` when technical choices matter. Keep requirements in the spec; put implementation choices here.
+
+```markdown
+# Design: [Change]
+
+## Context
+## Goals / Non-Goals
+## Decisions
+### Decision: [Choice]
+- **Choice:** ...
+- **Rationale:** ...
+- **Alternatives considered:** ...
+
+## Risks / Trade-offs
+## Migration / Rollback
+## Open Questions
+```
+
+## Tasks structure
+
+Use `tasks.md` only after the spec and design are stable enough to act on.
+
+```markdown
+# Tasks: [Change]
+
+## 1. Setup / Foundation
+- [ ] 1.1 [Concrete task with file path]
+
+## 2. Requirement: [Name]
+- [ ] 2.1 [Test or validation task]
+- [ ] 2.2 [Implementation task]
+
+## 3. Validation
+- [ ] 3.1 Run [command]
+- [ ] 3.2 Verify [observable behavior]
+```
+
+Tasks should be small enough for one agent session. Include file paths and validation commands when known.
+
+## Review checklist
+
+Before treating a spec as ready, check:
+
+- [ ] The `Why` names a real problem or opportunity.
+- [ ] The `Goal` is specific and measurable.
+- [ ] Scope has both in-scope and out-of-scope items.
+- [ ] Requirements use MUST or SHALL for mandatory behavior.
+- [ ] Each requirement has acceptance checks or scenarios.
+- [ ] Edge cases include failure and empty-state behavior where relevant.
+- [ ] Assumptions are visible.
+- [ ] Open questions are few and material.
+- [ ] Implementation details live in `design.md` or `tasks.md`, not in behavioral requirements.
+- [ ] The spec is concise, concrete, and free of promotional language.
+
+## Writing style
+
+Write for humans and agents. Prefer short sentences. Use active voice. Omit needless words. Avoid vague adjectives such as robust, seamless, powerful, and cutting-edge. Replace them with concrete behavior.
+
+Use tables only when they make comparison or traceability easier. Do not decorate specs with excessive emoji or bold text.

package/skills/builtin/prd/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: prd
+description: 'Generate high-quality Product Requirements Documents (PRDs) for software systems and AI-powered features. Includes executive summaries, user stories, technical specifications, and risk analysis.'
+license: MIT
+---
+
+# Product Requirements Document (PRD)
+
+## Overview
+
+Design comprehensive, production-grade Product Requirements Documents (PRDs) that bridge the gap between business vision and technical execution. This skill works for modern software systems, ensuring that requirements are clearly defined.
+
+## When to Use
+
+Use this skill when:
+
+- Starting a new product or feature development cycle
+- Translating a vague idea into a concrete technical specification
+- Defining requirements for AI-powered features
+- Stakeholders need a unified "source of truth" for project scope
+- User asks to "write a PRD", "document requirements", or "plan a feature"
+
+---
+
+## Operational Workflow
+
+### Phase 1: Discovery (The Interview)
+
+Before writing a single line of the PRD, you **MUST** interrogate the user to fill knowledge gaps. Do not assume context.
+
+**Ask about:**
+
+- **The Core Problem**: Why are we building this now?
+- **Success Metrics**: How do we know it worked?
+- **Constraints**: Budget, tech stack, or deadline?
+
+### Phase 2: Analysis & Scoping
+
+Synthesize the user's input. Identify dependencies and hidden complexities.
+
+- Map out the **User Flow**.
+- Define **Non-Goals** to protect the timeline.
+
+### Phase 3: Technical Drafting
+
+Generate the document using the **Strict PRD Schema** below.
+
+---
+
+## PRD Quality Standards
+
+### Requirements Quality
+
+Use concrete, measurable criteria. Avoid "fast", "easy", or "intuitive".
+
+```diff
+# Vague (BAD)
+- The search should be fast and return relevant results.
+- The UI must look modern and be easy to use.
+
+# Concrete (GOOD)
++ The search must return results within 200ms for a 10k record dataset.
++ The search algorithm must achieve >= 85% Precision@10 in benchmark evals.
++ The UI must follow the 'Vercel/Next.js' design system and achieve 100% Lighthouse Accessibility score.
+```
+
+---
+
+## Strict PRD Schema
+
+You **MUST** follow this exact structure for the output:
+
+### 1. Executive Summary
+
+- **Problem Statement**: 1-2 sentences on the pain point.
+- **Proposed Solution**: 1-2 sentences on the fix.
+- **Success Criteria**: 3-5 measurable KPIs.
+
+### 2. User Experience & Functionality
+
+- **User Personas**: Who is this for?
+- **User Stories**: `As a [user], I want to [action] so that [benefit].`
+- **Acceptance Criteria**: Bulleted list of "Done" definitions for each story.
+- **Non-Goals**: What are we NOT building?
+
+### 3. AI System Requirements (If Applicable)
+
+- **Tool Requirements**: What tools and APIs are needed?
+- **Evaluation Strategy**: How to measure output quality and accuracy.
+
+### 4. Technical Specifications
+
+- **Architecture Overview**: Data flow and component interaction.
+- **Integration Points**: APIs, DBs, and Auth.
+- **Security & Privacy**: Data handling and compliance.
+
+### 5. Risks & Roadmap
+
+- **Phased Rollout**: MVP -> v1.1 -> v2.0.
+- **Technical Risks**: Latency, cost, or dependency failures.
+
+---
+
+## Implementation Guidelines
+
+### DO (Always)
+
+- **Define Testing**: For AI systems, specify how to test and validate output quality.
+- **Iterate**: Present a draft and ask for feedback on specific sections.
+
+### DON'T (Avoid)
+
+- **Skip Discovery**: Never write a PRD without asking at least 2 clarifying questions first.
+- **Hallucinate Constraints**: If the user didn't specify a tech stack, ask or label it as `TBD`.
+
+---
+
+## Example: Intelligent Search System
+
+### 1. Executive Summary
+
+**Problem**: Users struggle to find specific documentation snippets in massive repositories.
+**Solution**: An intelligent search system that provides direct answers with source citations.
+**Success**:
+
+- Reduce search time by 50%.
+- Citation accuracy >= 95%.
+
+### 2. User Stories
+
+- **Story**: As a developer, I want to ask natural language questions so I don't have to guess keywords.
+- **AC**:
+  - Supports multi-turn clarification.
+  - Returns code blocks with "Copy" button.
+
+### 3. AI System Architecture
+
+- **Tools Required**: `codesearch`, `grep`, `webfetch`.
+
+### 4. Evaluation
+
+- **Benchmark**: Test with 50 common developer questions.
+- **Pass Rate**: 90% must match expected citations.