panopticon-cli 0.4.33 → 0.5.1

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/dist/chunk-7XNJJBH6.js

@@ -1,538 +0,0 @@
-import {
-  SETTINGS_FILE,
-  init_paths
-} from "./chunk-ZTFNYOC7.js";
-import {
-  __esm,
-  init_esm_shims
-} from "./chunk-ZHC57RCV.js";
-
-// src/lib/settings.ts
-import { readFileSync, writeFileSync, existsSync } from "fs";
-function deepMerge(defaults, overrides) {
-  const result = { ...defaults };
-  for (const key of Object.keys(overrides)) {
-    const defaultVal = defaults[key];
-    const overrideVal = overrides[key];
-    if (overrideVal === void 0) continue;
-    if (typeof defaultVal === "object" && defaultVal !== null && !Array.isArray(defaultVal) && typeof overrideVal === "object" && overrideVal !== null && !Array.isArray(overrideVal)) {
-      result[key] = deepMerge(defaultVal, overrideVal);
-    } else {
-      result[key] = overrideVal;
-    }
-  }
-  return result;
-}
-function loadSettings() {
-  let settings;
-  if (!existsSync(SETTINGS_FILE)) {
-    settings = getDefaultSettings();
-  } else {
-    try {
-      const content = readFileSync(SETTINGS_FILE, "utf8");
-      const parsed = JSON.parse(content);
-      settings = deepMerge(DEFAULT_SETTINGS, parsed);
-    } catch (error) {
-      console.error("Warning: Failed to parse settings.json, using defaults");
-      settings = getDefaultSettings();
-    }
-  }
-  const envApiKeys = {};
-  if (process.env.OPENAI_API_KEY) envApiKeys.openai = process.env.OPENAI_API_KEY;
-  if (process.env.GOOGLE_API_KEY) envApiKeys.google = process.env.GOOGLE_API_KEY;
-  if (process.env.ZAI_API_KEY) envApiKeys.zai = process.env.ZAI_API_KEY;
-  if (process.env.KIMI_API_KEY) envApiKeys.kimi = process.env.KIMI_API_KEY;
-  settings.api_keys = {
-    ...envApiKeys,
-    ...settings.api_keys
-  };
-  return settings;
-}
-function saveSettings(settings) {
-  const content = JSON.stringify(settings, null, 2);
-  writeFileSync(SETTINGS_FILE, content, "utf8");
-}
-function validateSettings(settings) {
-  if (!settings.models) {
-    return "Missing models configuration";
-  }
-  if (!settings.models.specialists) {
-    return "Missing specialists configuration";
-  }
-  const specialists = settings.models.specialists;
-  if (!specialists.review_agent || !specialists.test_agent || !specialists.merge_agent) {
-    return "Missing specialist agent model configuration";
-  }
-  if (!settings.models.complexity) {
-    return "Missing complexity configuration";
-  }
-  const complexity = settings.models.complexity;
-  const requiredLevels = ["trivial", "simple", "medium", "complex", "expert"];
-  for (const level of requiredLevels) {
-    if (!complexity[level]) {
-      return `Missing complexity level: ${level}`;
-    }
-  }
-  if (!settings.api_keys) {
-    return "Missing api_keys configuration";
-  }
-  return null;
-}
-function getDefaultSettings() {
-  return JSON.parse(JSON.stringify(DEFAULT_SETTINGS));
-}
-function getAvailableModels(settings) {
-  const anthropicModels = [
-    "claude-opus-4-6",
-    "claude-sonnet-4-6",
-    "claude-haiku-4-5"
-  ];
-  const openaiModels = settings.api_keys.openai ? ["gpt-5.2-codex", "o3-deep-research", "gpt-4o", "gpt-4o-mini"] : [];
-  const googleModels = settings.api_keys.google ? ["gemini-3-pro-preview", "gemini-3-flash-preview"] : [];
-  const zaiModels = settings.api_keys.zai ? ["glm-4.7", "glm-4.7-flash"] : [];
-  const kimiModels = settings.api_keys.kimi ? ["kimi-k2", "kimi-k2.5"] : [];
-  return {
-    anthropic: anthropicModels,
-    openai: openaiModels,
-    google: googleModels,
-    zai: zaiModels,
-    kimi: kimiModels
-  };
-}
-function isAnthropicModel(modelId) {
-  return modelId.startsWith("claude-");
-}
-function getClaudeModelFlag(modelId) {
-  const modelMap = {
-    "claude-opus-4-6": "opus",
-    "claude-sonnet-4-6": "sonnet",
-    "claude-sonnet-4-5": "sonnet",
-    "claude-haiku-4-5": "haiku"
-  };
-  return modelMap[modelId] || "sonnet";
-}
-function getAgentCommand(modelId) {
-  if (isAnthropicModel(modelId)) {
-    return {
-      command: "claude",
-      args: ["--model", getClaudeModelFlag(modelId)]
-    };
-  }
-  return {
-    command: "claude-code-router",
-    args: []
-  };
-}
-var DEFAULT_SETTINGS;
-var init_settings = __esm({
-  "src/lib/settings.ts"() {
-    "use strict";
-    init_esm_shims();
-    init_paths();
-    DEFAULT_SETTINGS = {
-      models: {
-        specialists: {
-          review_agent: "claude-opus-4-6",
-          test_agent: "claude-sonnet-4-6",
-          merge_agent: "claude-sonnet-4-6"
-        },
-        status_review: "claude-opus-4-6",
-        complexity: {
-          trivial: "claude-haiku-4-5",
-          simple: "claude-haiku-4-5",
-          medium: "kimi-k2.5",
-          complex: "kimi-k2.5",
-          expert: "claude-opus-4-6"
-        }
-      },
-      api_keys: {}
-    };
-  }
-});
-
-// src/lib/providers.ts
-import { existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
-import { join } from "path";
-function getProviderForModel(modelId) {
-  if (["claude-opus-4-6", "claude-sonnet-4-6", "claude-sonnet-4-5", "claude-haiku-4-5"].includes(modelId)) {
-    return PROVIDERS.anthropic;
-  }
-  if (["gpt-5.2-codex", "o3-deep-research", "gpt-4o", "gpt-4o-mini"].includes(modelId)) {
-    return PROVIDERS.openai;
-  }
-  if (["gemini-3-pro-preview", "gemini-3-flash-preview"].includes(modelId)) {
-    return PROVIDERS.google;
-  }
-  if (["glm-4.7", "glm-4.7-flash"].includes(modelId)) {
-    return PROVIDERS.zai;
-  }
-  if (["kimi-k2", "kimi-k2.5"].includes(modelId)) {
-    return PROVIDERS.kimi;
-  }
-  return PROVIDERS.anthropic;
-}
-function requiresRouter(provider) {
-  return PROVIDERS[provider].compatibility === "router";
-}
-function getRouterProviders() {
-  return Object.values(PROVIDERS).filter((p) => p.compatibility === "router");
-}
-function getDirectProviders() {
-  return Object.values(PROVIDERS).filter((p) => p.compatibility === "direct");
-}
-function needsRouter(apiKeys) {
-  return !!(apiKeys.openai || apiKeys.google);
-}
-function getProviderEnv(provider, apiKey) {
-  if (provider.compatibility === "direct") {
-    const env = {};
-    if (provider.baseUrl) {
-      env.ANTHROPIC_BASE_URL = provider.baseUrl;
-    }
-    if (provider.name !== "anthropic") {
-      if (provider.authType === "credential-file") {
-        env.ANTHROPIC_AUTH_TOKEN = apiKey;
-        env.CLAUDE_CODE_API_KEY_HELPER_TTL_MS = "60000";
-      } else {
-        env.ANTHROPIC_AUTH_TOKEN = apiKey;
-      }
-    }
-    if (provider.name === "zai") {
-      env.API_TIMEOUT_MS = "300000";
-    }
-    return env;
-  } else {
-    return {
-      ANTHROPIC_BASE_URL: "http://localhost:3456",
-      ANTHROPIC_AUTH_TOKEN: "router-managed"
-    };
-  }
-}
-function setupCredentialFileAuth(provider, workspacePath) {
-  if (provider.authType !== "credential-file" || !provider.credentialHelper) return;
-  const helperPath = provider.credentialHelper.replace("~", process.env.HOME || "");
-  const claudeDir = join(workspacePath, ".claude");
-  const settingsPath = join(claudeDir, "settings.local.json");
-  if (!existsSync2(claudeDir)) {
-    mkdirSync(claudeDir, { recursive: true });
-  }
-  let settings = {};
-  if (existsSync2(settingsPath)) {
-    try {
-      settings = JSON.parse(readFileSync2(settingsPath, "utf-8"));
-    } catch {
-    }
-  }
-  settings.apiKeyHelper = helperPath;
-  writeFileSync2(settingsPath, JSON.stringify(settings, null, 2) + "\n");
-}
-var PROVIDERS;
-var init_providers = __esm({
-  "src/lib/providers.ts"() {
-    "use strict";
-    init_esm_shims();
-    PROVIDERS = {
-      anthropic: {
-        name: "anthropic",
-        displayName: "Anthropic",
-        compatibility: "direct",
-        models: ["claude-opus-4-6", "claude-sonnet-4-6", "claude-sonnet-4-5", "claude-haiku-4-5"],
-        tested: true,
-        description: "Native Claude API"
-      },
-      kimi: {
-        name: "kimi",
-        displayName: "Kimi (Moonshot AI)",
-        compatibility: "direct",
-        baseUrl: "https://api.kimi.com/coding/",
-        authType: "credential-file",
-        credentialFile: "~/.kimi/credentials/kimi-code.json",
-        credentialHelper: "~/.panopticon/bin/kimi-token-helper.sh",
-        models: [],
-        // Kimi uses same model names as Anthropic
-        tested: true,
-        description: "Anthropic-compatible API via Kimi Code Plan (OAuth token refresh)"
-      },
-      zai: {
-        name: "zai",
-        displayName: "Z.AI (GLM)",
-        compatibility: "direct",
-        baseUrl: "https://api.z.ai/api/anthropic",
-        models: ["glm-4.7", "glm-4.7-flash"],
-        tested: true,
-        description: "Anthropic-compatible API, tested 2026-01-28"
-      },
-      openai: {
-        name: "openai",
-        displayName: "OpenAI",
-        compatibility: "router",
-        models: ["gpt-5.2-codex", "o3-deep-research", "gpt-4o", "gpt-4o-mini"],
-        tested: false,
-        description: "Requires claude-code-router for API translation"
-      },
-      google: {
-        name: "google",
-        displayName: "Google (Gemini)",
-        compatibility: "router",
-        models: ["gemini-3-pro-preview", "gemini-3-flash-preview"],
-        tested: false,
-        description: "Requires claude-code-router for API translation"
-      }
-    };
-  }
-});
-
-// src/lib/config-yaml.ts
-import { readFileSync as readFileSync3, existsSync as existsSync3 } from "fs";
-import { join as join2 } from "path";
-import { homedir } from "os";
-import yaml from "js-yaml";
-function normalizeProviderConfig(providerConfig, fallbackKey) {
-  if (providerConfig === void 0) {
-    return { enabled: false };
-  }
-  if (typeof providerConfig === "boolean") {
-    return { enabled: providerConfig, api_key: fallbackKey };
-  }
-  return {
-    enabled: providerConfig.enabled,
-    api_key: providerConfig.api_key || fallbackKey
-  };
-}
-function resolveEnvVar(value) {
-  if (!value) return void 0;
-  return value.replace(/\$\{?([A-Z_][A-Z0-9_]*)\}?/g, (match, varName) => {
-    const envValue = process.env[varName];
-    return envValue !== void 0 ? envValue : match;
-  });
-}
-function loadYamlFile(filePath) {
-  if (!existsSync3(filePath)) {
-    return null;
-  }
-  try {
-    const content = readFileSync3(filePath, "utf-8");
-    const parsed = yaml.load(content);
-    return parsed || {};
-  } catch (error) {
-    console.error(`Error loading YAML config from ${filePath}:`, error);
-    return null;
-  }
-}
-function findProjectRoot(startDir = process.cwd()) {
-  let currentDir = startDir;
-  while (currentDir !== "/") {
-    if (existsSync3(join2(currentDir, ".git"))) {
-      return currentDir;
-    }
-    currentDir = join2(currentDir, "..");
-  }
-  return null;
-}
-function loadProjectConfig() {
-  const projectRoot = findProjectRoot();
-  if (!projectRoot) {
-    return null;
-  }
-  const projectConfigPath = join2(projectRoot, ".panopticon.yaml");
-  return loadYamlFile(projectConfigPath);
-}
-function loadGlobalConfig() {
-  return loadYamlFile(GLOBAL_CONFIG_PATH);
-}
-function mergeShadowConfig(result, config) {
-  if (!config?.shadow) return;
-  if (config.shadow.enabled !== void 0) {
-    result.enabled = config.shadow.enabled;
-  }
-  if (config.shadow.trackers) {
-    if (config.shadow.trackers.linear !== void 0) {
-      result.trackers.linear = config.shadow.trackers.linear;
-    }
-    if (config.shadow.trackers.github !== void 0) {
-      result.trackers.github = config.shadow.trackers.github;
-    }
-    if (config.shadow.trackers.gitlab !== void 0) {
-      result.trackers.gitlab = config.shadow.trackers.gitlab;
-    }
-    if (config.shadow.trackers.rally !== void 0) {
-      result.trackers.rally = config.shadow.trackers.rally;
-    }
-  }
-}
-function mergeConfigs(...configs) {
-  const result = {
-    ...DEFAULT_CONFIG,
-    enabledProviders: new Set(DEFAULT_CONFIG.enabledProviders),
-    shadow: {
-      enabled: DEFAULT_CONFIG.shadow.enabled,
-      trackers: { ...DEFAULT_CONFIG.shadow.trackers }
-    }
-  };
-  const validConfigs = configs.filter((c) => c !== null);
-  for (const config of validConfigs.reverse()) {
-    if (config.models?.providers) {
-      const providers = config.models.providers;
-      const legacyKeys = config.api_keys || {};
-      result.enabledProviders.add("anthropic");
-      const openai = normalizeProviderConfig(providers.openai, legacyKeys.openai);
-      if (openai.enabled) {
-        result.enabledProviders.add("openai");
-        if (openai.api_key) {
-          result.apiKeys.openai = resolveEnvVar(openai.api_key);
-        }
-      }
-      const google = normalizeProviderConfig(providers.google, legacyKeys.google);
-      if (google.enabled) {
-        result.enabledProviders.add("google");
-        if (google.api_key) {
-          result.apiKeys.google = resolveEnvVar(google.api_key);
-        }
-      }
-      const zai = normalizeProviderConfig(providers.zai, legacyKeys.zai);
-      if (zai.enabled) {
-        result.enabledProviders.add("zai");
-        if (zai.api_key) {
-          result.apiKeys.zai = resolveEnvVar(zai.api_key);
-        }
-      }
-      const kimi = normalizeProviderConfig(providers.kimi, legacyKeys.kimi);
-      if (kimi.enabled) {
-        result.enabledProviders.add("kimi");
-        if (kimi.api_key) {
-          result.apiKeys.kimi = resolveEnvVar(kimi.api_key);
-        }
-      }
-    }
-    if (config.api_keys) {
-      if (config.api_keys.openai) {
-        result.apiKeys.openai = resolveEnvVar(config.api_keys.openai);
-        result.enabledProviders.add("openai");
-      }
-      if (config.api_keys.google) {
-        result.apiKeys.google = resolveEnvVar(config.api_keys.google);
-        result.enabledProviders.add("google");
-      }
-      if (config.api_keys.zai) {
-        result.apiKeys.zai = resolveEnvVar(config.api_keys.zai);
-        result.enabledProviders.add("zai");
-      }
-      if (config.api_keys.kimi) {
-        result.apiKeys.kimi = resolveEnvVar(config.api_keys.kimi);
-        result.enabledProviders.add("kimi");
-      }
-    }
-    if (config.models?.overrides) {
-      result.overrides = {
-        ...result.overrides,
-        ...config.models.overrides
-      };
-    }
-    if (config.models?.gemini_thinking_level) {
-      result.geminiThinkingLevel = config.models.gemini_thinking_level;
-    }
-    if (config.tracker_keys) {
-      if (config.tracker_keys.linear) {
-        result.trackerKeys.linear = resolveEnvVar(config.tracker_keys.linear);
-      }
-      if (config.tracker_keys.github) {
-        result.trackerKeys.github = resolveEnvVar(config.tracker_keys.github);
-      }
-      if (config.tracker_keys.gitlab) {
-        result.trackerKeys.gitlab = resolveEnvVar(config.tracker_keys.gitlab);
-      }
-      if (config.tracker_keys.rally) {
-        result.trackerKeys.rally = resolveEnvVar(config.tracker_keys.rally);
-      }
-    }
-    mergeShadowConfig(result.shadow, config);
-  }
-  return result;
-}
-function loadConfig() {
-  const globalConfig = loadGlobalConfig();
-  const projectConfig = loadProjectConfig();
-  const config = mergeConfigs(projectConfig, globalConfig);
-  if (process.env.OPENAI_API_KEY && !config.apiKeys.openai) {
-    config.apiKeys.openai = process.env.OPENAI_API_KEY;
-    config.enabledProviders.add("openai");
-  }
-  if (process.env.GOOGLE_API_KEY && !config.apiKeys.google) {
-    config.apiKeys.google = process.env.GOOGLE_API_KEY;
-    config.enabledProviders.add("google");
-  }
-  if (process.env.ZAI_API_KEY && !config.apiKeys.zai) {
-    config.apiKeys.zai = process.env.ZAI_API_KEY;
-    config.enabledProviders.add("zai");
-  }
-  if (process.env.KIMI_API_KEY && !config.apiKeys.kimi) {
-    config.apiKeys.kimi = process.env.KIMI_API_KEY;
-    config.enabledProviders.add("kimi");
-  }
-  if (process.env.LINEAR_API_KEY && !config.trackerKeys.linear) {
-    config.trackerKeys.linear = process.env.LINEAR_API_KEY;
-  }
-  if (process.env.GITHUB_TOKEN && !config.trackerKeys.github) {
-    config.trackerKeys.github = process.env.GITHUB_TOKEN;
-  }
-  if (process.env.GITLAB_TOKEN && !config.trackerKeys.gitlab) {
-    config.trackerKeys.gitlab = process.env.GITLAB_TOKEN;
-  }
-  if (process.env.RALLY_API_KEY && !config.trackerKeys.rally) {
-    config.trackerKeys.rally = process.env.RALLY_API_KEY;
-  }
-  if (process.env.SHADOW_MODE !== void 0) {
-    const envShadowMode = ["true", "1", "yes"].includes(process.env.SHADOW_MODE.toLowerCase());
-    config.shadow.enabled = envShadowMode;
-  }
-  return config;
-}
-var DEFAULT_CONFIG, GLOBAL_CONFIG_PATH;
-var init_config_yaml = __esm({
-  "src/lib/config-yaml.ts"() {
-    "use strict";
-    init_esm_shims();
-    DEFAULT_CONFIG = {
-      enabledProviders: /* @__PURE__ */ new Set(["anthropic"]),
-      // Only Anthropic by default
-      apiKeys: {},
-      overrides: {},
-      geminiThinkingLevel: 3,
-      trackerKeys: {},
-      shadow: {
-        enabled: false,
-        trackers: {
-          linear: false,
-          github: false,
-          gitlab: false,
-          rally: false
-        }
-      }
-    };
-    GLOBAL_CONFIG_PATH = join2(homedir(), ".panopticon", "config.yaml");
-  }
-});
-
-export {
-  loadSettings,
-  saveSettings,
-  validateSettings,
-  getDefaultSettings,
-  getAvailableModels,
-  isAnthropicModel,
-  getClaudeModelFlag,
-  getAgentCommand,
-  init_settings,
-  loadConfig,
-  init_config_yaml,
-  PROVIDERS,
-  getProviderForModel,
-  requiresRouter,
-  getRouterProviders,
-  getDirectProviders,
-  needsRouter,
-  getProviderEnv,
-  setupCredentialFileAuth,
-  init_providers
-};
-//# sourceMappingURL=chunk-7XNJJBH6.js.map