panopticon-cli 0.4.32 → 0.5.0

package/skills/spec-readiness-setup/SKILL.md

@@ -0,0 +1,361 @@
+---
+name: spec-readiness-setup
+description: >
+  Create a customized wrapper for the spec-readiness skill. Configures branding,
+  issue tracker bindings, field mappings, and org-specific conventions. Generates
+  a ready-to-use wrapper skill directory with config.yaml and SKILL.md.
+triggers:
+  - spec readiness setup
+  - setup spec readiness
+  - configure spec readiness
+  - create readiness wrapper
+  - customize readiness skill
+  - spec readiness branding
+  - brand readiness report
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+# Spec Readiness Setup — Wrapper Creator
+
+This skill creates a customized wrapper for the `spec-readiness` core skill. The wrapper binds your organization's branding, issue tracker, field names, and conventions to the generic scoring engine.
+
+## What Gets Created
+
+```
+~/.panopticon/skills/spec-readiness-{name}/
+  SKILL.md       # Wrapper skill that invokes the core with your config
+  config.yaml    # Branding, tracker bindings, field mappings, conventions
+```
+
+After creation, the wrapper is immediately available. Users invoke it by name (e.g., `spec readiness acme MIN-704`) or the core skill auto-detects it.
+
+---
+
+## Workflow
+
+### Step 1: Gather Information
+
+Ask the user the following questions. Use `AskUserQuestion` with sensible defaults. Skip questions the user has already answered in their prompt.
+
+**1. Wrapper name** (used in directory name and skill name):
+- "What should this wrapper be called? This becomes the skill name, e.g., `spec-readiness-acme`"
+- Default: derive from company name (lowercase, kebab-case)
+- Validation: kebab-case, no spaces, alphanumeric + hyphens only
+
+**2. Company / Organization name** (for report branding):
+- "What company or team name should appear on reports?"
+- This appears in the HTML report header and footer
+
+**3. Issue tracker**:
+- "Which issue tracker do you use?"
+- Options: Linear, GitHub Issues, GitLab Issues, Rally, Jira, Other
+- If Other: ask for details, we'll create a custom mapping
+
+**4. Branding colors** (optional):
+- "Do you have brand colors for the report? (Enter hex codes or skip for defaults)"
+- Primary color (header/accents): default `#1e293b` (dark slate)
+- Stripe color (top bar): default matches primary
+- If the user has an existing branding skill, offer to read colors from it
+
+**5. Tracker-specific fields** (based on tracker choice):
+
+For **Linear**:
+- "What's your team name in Linear?"
+- "Do you use a label for customer-directed issues? (e.g., 'Customer Request')"
+
+For **GitHub**:
+- "What's the repo (owner/name)?"
+- "Do you use labels for epics/features? (e.g., 'epic')"
+
+For **GitLab**:
+- "What's the project path?"
+- "Do you use epics or parent issues for features?"
+
+For **Rally**:
+- "What's the MCP tool prefix for your Rally MCP server?"
+- "Do you have a custom estimate field? (e.g., `c_ManDays`)"
+- "Do you have an investment category field for customer-directed work?"
+
+For **Jira**:
+- "What's your Jira instance URL?"
+- "Do you use Epics or another issue type for features?"
+- "Custom estimate field name? (e.g., `story_points`, `customfield_10016`)"
+
+**6. Org-specific conventions** (optional):
+- "Do you use any naming patterns for overflow/carryover issues? (e.g., `[Unfinished]`, `[Part 2]`)"
+- "Do you use any naming patterns for spike/investigation issues? (e.g., `SPIKE:`, `[Investigation]`)"
+- "Any custom footer text for reports?"
+
+### Step 2: Build Tracker Tool Mapping
+
+Based on the tracker choice, generate the tool mapping. These are the MCP tools or CLI commands the core skill will use.
+
+**Linear:**
+```yaml
+tracker:
+  type: linear
+  team: "{team_name}"
+  tools:
+    get_issue: "mcp__linear__get_issue"
+    list_child_issues: "mcp__linear__list_issues"
+    get_comments: "mcp__linear__list_comments"
+    search_issues: "mcp__linear__list_issues"
+    get_relations: "mcp__linear__get_issue"  # with includeRelations=true
+    get_activity_log: null  # not available in Linear
+  fields:
+    identifier: "identifier"
+    estimate: "estimate"
+    status: "status"
+    parent_field: "parentId"
+    customer_directed_label: "{label_or_null}"
+    overflow_markers: []
+```
+
+**GitHub:**
+```yaml
+tracker:
+  type: github
+  repo: "{owner}/{repo}"
+  tools:
+    get_issue: "bash:gh issue view {id} --repo {repo} --json title,body,state,labels,milestone,assignees,comments"
+    list_child_issues: "bash:gh issue list --repo {repo} --search 'parent:{id}' --json number,title,body,state,createdAt"
+    get_comments: "bash:gh issue view {id} --repo {repo} --json comments"
+    search_issues: "bash:gh issue list --repo {repo} --label bug --search '{query}' --json number,title,state"
+    get_relations: "bash:gh issue view {id} --repo {repo} --json body"  # parse from body
+    get_activity_log: "bash:gh api repos/{repo}/issues/{id}/events"
+  fields:
+    identifier: "number"
+    estimate: null  # GitHub has no native estimate field
+    status: "state"
+    parent_field: null  # GitHub uses tasklist / sub-issue references
+    customer_directed_label: "{label_or_null}"
+    overflow_markers: []
+```
+
+**GitLab:**
+```yaml
+tracker:
+  type: gitlab
+  project: "{project_path}"
+  tools:
+    get_issue: "bash:glab issue view {id}"
+    list_child_issues: "bash:glab api '/projects/{project_id}/issues?parent_id={id}'"
+    get_comments: "bash:glab issue note list {id}"
+    search_issues: "bash:glab issue list --label bug --search '{query}'"
+    get_relations: "bash:glab api '/projects/{project_id}/issues/{id}/links'"
+    get_activity_log: "bash:glab api '/projects/{project_id}/issues/{id}/resource_state_events'"
+  fields:
+    identifier: "iid"
+    estimate: "weight"
+    status: "state"
+    parent_field: "parent_id"
+    customer_directed_label: "{label_or_null}"
+    overflow_markers: []
+```
+
+**Rally:**
+```yaml
+tracker:
+  type: rally
+  tools:
+    get_issue: "{mcp_prefix}__get_feature"
+    get_story: "{mcp_prefix}__get_story"
+    get_defect: "{mcp_prefix}__get_defect"
+    list_child_issues: null  # from _collections.UserStories in feature response
+    get_comments: null  # from Discussion collection
+    search_issues: "{mcp_prefix}__search_work_items"
+    get_relations: null  # from Predecessors/Successors collections
+    get_activity_log: "{mcp_prefix}__get_revision_history"
+    search_risks: "{mcp_prefix}__search_risks"
+  fields:
+    identifier: "FormattedID"
+    estimate: "{custom_estimate_field_or_PlanEstimate}"
+    status: "ScheduleState"
+    parent_field: null  # Rally uses Feature→UserStory hierarchy
+    customer_directed_label: null
+    investment_category_field: "{field_or_null}"
+    investment_category_value: "{value_or_null}"
+    overflow_markers:
+      - "[Unfinished]"
+      - "[Continued]"
+```
+
+**Jira:**
+```yaml
+tracker:
+  type: jira
+  url: "{jira_url}"
+  tools:
+    get_issue: "bash:curl -s -H 'Authorization: Bearer $JIRA_TOKEN' '{jira_url}/rest/api/3/issue/{id}'"
+    list_child_issues: "bash:curl -s -H 'Authorization: Bearer $JIRA_TOKEN' '{jira_url}/rest/api/2/search?jql=parent={id}'"
+    get_comments: "bash:curl -s -H 'Authorization: Bearer $JIRA_TOKEN' '{jira_url}/rest/api/3/issue/{id}/comment'"
+    search_issues: "bash:curl -s -H 'Authorization: Bearer $JIRA_TOKEN' '{jira_url}/rest/api/2/search?jql={jql}'"
+    get_relations: "bash:curl -s -H 'Authorization: Bearer $JIRA_TOKEN' '{jira_url}/rest/api/3/issue/{id}?fields=issuelinks'"
+    get_activity_log: "bash:curl -s -H 'Authorization: Bearer $JIRA_TOKEN' '{jira_url}/rest/api/3/issue/{id}/changelog'"
+  fields:
+    identifier: "key"
+    estimate: "{custom_field_or_story_points}"
+    status: "status.name"
+    parent_field: "parent.key"
+    customer_directed_label: "{label_or_null}"
+    overflow_markers: []
+```
+
+### Step 3: Generate config.yaml
+
+Assemble the full config from gathered information:
+
+```yaml
+# Spec Readiness Wrapper: {wrapper_name}
+# Generated by spec-readiness-setup on {date}
+
+tracker:
+  type: {type}
+  # ... tracker-specific fields from Step 2
+
+branding:
+  company_name: "{company_name}"
+  primary_color: "{primary_color}"
+  stripe_color: "{stripe_color}"
+  footer_text: "{footer_text_or_null}"
+  logo_url: null
+
+conventions:
+  overflow_markers: {markers_list}
+  spike_patterns:
+    - "spike"
+    - "investigation"
+    - "discovery"
+    - "POC"
+    - "prototype"
+    - "analysis"
+    # ... plus any user-specified patterns
+  estimate_field_custom: "{custom_field_or_null}"
+  investment_category_field: "{field_or_null}"
+  investment_category_value: "{value_or_null}"
+```
+
+### Step 4: Generate Wrapper SKILL.md
+
+Create the wrapper skill that invokes the core:
+
+```markdown
+---
+name: spec-readiness-{name}
+description: >
+  {company_name}-branded requirements readiness scoring. Wraps the core
+  spec-readiness skill with {company_name} branding and {tracker_type}
+  tracker integration. Score issues 0-100 across 5 dimensions.
+triggers:
+  - spec readiness {name}
+  - {name} readiness
+  - {name} spec score
+  # ... include all core triggers too
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - WebFetch
+  - Task
+  {tracker_specific_tools}
+---
+
+# Spec Readiness — {company_name}
+
+This is a branded wrapper for the `spec-readiness` core skill.
+
+## Configuration
+
+- **Tracker:** {tracker_type}
+- **Branding:** {company_name}
+- **Config:** ~/.panopticon/skills/spec-readiness-{name}/config.yaml
+
+## Usage
+
+Invoke exactly like the core skill. This wrapper is auto-detected:
+
+```
+spec readiness {example_id}
+how ready is {example_id}
+readiness check {example_id}
+```
+
+## How It Works
+
+1. This wrapper sets the configuration context (branding, tracker, field mappings)
+2. The core `spec-readiness` skill runs the scoring engine
+3. Reports are generated with {company_name} branding
+
+**To modify configuration**, edit:
+`~/.panopticon/skills/spec-readiness-{name}/config.yaml`
+
+**To update the scoring model**, the core skill at
+`~/.panopticon/skills/spec-readiness/SKILL.md` controls all scoring logic.
+```
+
+### Step 5: Write Files
+
+```bash
+mkdir -p ~/.panopticon/skills/spec-readiness-{name}
+write config.yaml to ~/.panopticon/skills/spec-readiness-{name}/config.yaml
+write SKILL.md to ~/.panopticon/skills/spec-readiness-{name}/SKILL.md
+```
+
+### Step 6: Verify and Report
+
+1. Confirm both files were written
+2. Show the user a summary:
+
+```
+Created spec-readiness wrapper: spec-readiness-{name}
+
+  Location: ~/.panopticon/skills/spec-readiness-{name}/
+  Tracker:  {tracker_type}
+  Branding: {company_name} ({primary_color})
+
+  Files:
+    config.yaml  — tracker bindings, branding, conventions
+    SKILL.md     — wrapper skill definition
+
+  Usage:
+    spec readiness {example_id}
+
+  To customize further, edit:
+    ~/.panopticon/skills/spec-readiness-{name}/config.yaml
+```
+
+3. Ask if they want to run a test assessment on a real issue to verify the setup
+
+---
+
+## Updating an Existing Wrapper
+
+If the user runs this skill and a wrapper already exists:
+
+1. Read the existing `config.yaml`
+2. Show current configuration
+3. Ask what they want to change
+4. Update only the changed fields
+5. Preserve any manual customizations
+
+---
+
+## Examples
+
+```
+User: setup spec readiness
+→ Full wizard: asks all questions
+
+User: create readiness wrapper for Acme using Linear
+→ Skips tracker question, asks remaining
+
+User: configure spec readiness for our team using GitHub Issues on eltmon/panopticon-cli
+→ Skips tracker question and repo question
+
+User: spec readiness branding — change colors to #0891b2
+→ Updates existing wrapper branding only
+```

package/skills/workspace-status/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: workspace-status
+description: Auto-applied when reporting on agent/workspace status. Displays robust workspace information with URLs and commands.
+---
+
+# Workspace Status Display Format
+
+When discussing agent status, workspace setup, or providing updates about spawned agents, ALWAYS include this comprehensive table format.
+
+## Required Information Table
+
+Display workspace details in this exact format:
+
+```markdown
+## Agent: {ISSUE_ID} - {ISSUE_TITLE}
+
+| Field | Value |
+|-------|-------|
+| Issue | {TRACKER_URL} |
+| PR/MR | {PR_OR_MR_URL} (if available) |
+| Workspace | {WORKSPACE_PATH} |
+| **Frontend** | https://feature-{issue-id-lowercase}.{PROJECT_DOMAIN} |
+| **API** | https://api-feature-{issue-id-lowercase}.{PROJECT_DOMAIN} |
+| tmux Session | agent-{issue-id-lowercase} |
+
+## Commands
+
+| Action | Command |
+|--------|---------|
+| **Watch agent** | `tmux attach -t agent-{issue-id-lowercase}` |
+| **Send feedback** | `pan tell {ISSUE_ID} "your message"` |
+| **Approve & merge** | `pan approve {ISSUE_ID}` |
+| Detach | `Ctrl+b` then `d` |
+| Kill | `tmux kill-session -t agent-{issue-id-lowercase}` |
+| Resources | `htop` or `watch -n 5 'free -h'` |
+```
+
+## When to Apply This Format
+
+Use this format when:
+- Spawning a new agent
+- Reporting agent completion
+- Providing agent status updates
+- Resuming or restarting an agent
+- User asks about an agent's status
+- Providing investigation/spike results
+
+## Additional Context (Optional)
+
+After the tables, you may add additional context like:
+- Investigation plan or next steps
+- Important notes about the workspace
+- Special setup or requirements
+- Resource availability status
+
+The tables should ALWAYS come first, followed by any additional narrative.

package/skills/write-spec/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: write-spec
+description: >
+  Write a feature spec (*-spec.md) for an issue. The spec is the human-written
+  requirements document that feeds into the planning agent. Part of the
+  spec → plan → implement pipeline.
+triggers:
+  - write spec
+  - write-spec
+  - create spec
+  - feature spec
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - ToolSearch
+version: "1.0.0"
+author: "Ed Becker"
+license: "MIT"
+---
+
+# Write Feature Spec
+
+**Trigger:** `/write-spec <issue-id>` or `/write-spec <issue-id> <title>`
+
+## The Spec → Plan Pipeline
+
+Panopticon uses a two-stage planning process:
+
+1. **Spec** (`*-spec.md`) — Human-written (often with AI assistance). Defines WHAT to build and WHY. Contains requirements, constraints, scope, research, and design decisions.
+2. **Plan** (`*-plan.md`) — Generated by the planning agent. Defines HOW to build it. Contains architecture, tasks with dependencies, file-level changes, and difficulty estimates.
+
+The planning agent reads the spec as its primary input, explores the codebase, asks clarifying questions, then produces the implementation plan.
+
+## When to Write a Spec
+
+- **Complex features** (multi-file, cross-cutting, architectural) — always write a spec first
+- **Features with research** — when you've explored options, talked to stakeholders, or analyzed competitors
+- **Features with constraints** — when there are specific technical or UX requirements the agent needs to know
+- **Simple bug fixes or small changes** — skip the spec, go directly to planning or implementation
+
+## Execution Steps
+
+### 1. Identify the Issue
+
+Parse the issue ID from the command argument. Determine the project:
+- `MIN-XXX` → MYN project, docs at `/home/eltmon/Projects/myn/docs/`
+- `PAN-XXX` → Panopticon project, docs at `/home/eltmon/Projects/panopticon-cli/docs/`
+
+### 2. Gather Context
+
+- Fetch the issue from the tracker (Linear for MIN, GitHub for PAN) to get title, description, comments
+- Check if a spec already exists at `docs/prds/active/{issue-id-lowercase}-*-spec.md`
+- If updating an existing spec, read it first
+
+### 3. Research (Interactive)
+
+Use AskUserQuestion or discussion to understand:
+- What problem does this solve?
+- Who benefits?
+- What's in scope vs out of scope?
+- Any technical constraints or preferences?
+- Are there related specs or prior art to reference?
+
+### 4. Write the Spec
+
+Create the file at: `docs/prds/active/{issue-id-lowercase}-{short-title}-spec.md`
+
+Use this structure:
+
+```markdown
+# {Issue ID}: {Title}
+
+## Problem Statement
+What problem does this solve? Why does it matter?
+
+## Requirements
+### Must Have
+- Requirement 1
+- Requirement 2
+
+### Should Have
+- Nice-to-have 1
+
+### Out of Scope
+- Explicitly excluded items
+
+## Design
+### User Experience
+How should it work from the user's perspective?
+
+### Technical Approach
+High-level technical direction (NOT implementation details — that's for the plan).
+
+### Constraints
+- Performance requirements
+- Compatibility requirements
+- Security considerations
+
+## References
+- Related issues: MIN-XXX, MIN-YYY
+- Prior art: links to existing code, docs, or external references
+- Research: any analysis or competitor research
+
+## Open Questions
+- Questions to resolve during planning
+```
+
+### 5. Confirm File Location
+
+After writing, confirm:
+```
+Spec written: docs/prds/active/{filename}-spec.md
+
+Next steps:
+1. Review and edit the spec as needed
+2. Click "Plan" on the issue in the dashboard
+3. The planning agent will read this spec and produce an implementation plan
+```
+
+## File Naming Convention
+
+| Type | Pattern | Created By | Example |
+|------|---------|-----------|---------|
+| Spec | `{issue-id}-{title}-spec.md` | Human (this skill) | `min-734-kaia-openclaw-a2a-spec.md` |
+| Plan | `{issue-id}-plan.md` | Planning agent | `min-734-plan.md` |
+
+Both live in `docs/prds/active/`. Specs are never overwritten by agents.
+
+## Important Notes
+
+- **Specs are for humans** — write clearly, include context and rationale
+- **Plans are for agents** — the planning agent produces structured, actionable tasks
+- **Don't over-specify implementation** — the planning agent + codebase exploration will figure out the HOW
+- **DO specify constraints** — things the agent can't discover on its own (performance targets, UX requirements, API contracts)
+- **Reference existing code** — point to patterns, files, or modules the agent should follow

package/templates/traefik/dynamic/panopticon.yml.template

@@ -36,8 +36,3 @@ http:
       loadBalancer:
         servers:
           - url: "http://host.docker.internal:{{DASHBOARD_API_PORT}}"
-
-tls:
-  certificates:
-    - certFile: /etc/traefik/certs/_wildcard.{{TRAEFIK_DOMAIN}}.pem
-      keyFile: /etc/traefik/certs/_wildcard.{{TRAEFIK_DOMAIN}}-key.pem

package/templates/traefik/traefik.yml

@@ -43,11 +43,3 @@ log:
 # Access Logs
 accessLog:
   format: common
-
-# TLS Configuration
-tls:
-  stores:
-    default:
-      defaultCertificate:
-        certFile: /etc/traefik/certs/_wildcard.pan.localhost.pem
-        keyFile: /etc/traefik/certs/_wildcard.pan.localhost-key.pem