From 8cd173a09c012efe0dda0c294e31f004d638db2b Mon Sep 17 00:00:00 2001 From: "ecc-tools[bot]" <257055122+ecc-tools[bot]@users.noreply.github.com> Date: Wed, 29 Jul 2026 00:47:36 +0000 Subject: [PATCH 01/14] feat: add periscope ECC bundle (.claude/ecc-tools.json) --- .claude/ecc-tools.json | 286 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 286 insertions(+) create mode 100644 .claude/ecc-tools.json diff --git a/.claude/ecc-tools.json b/.claude/ecc-tools.json new file mode 100644 index 000000000..e48013086 --- /dev/null +++ b/.claude/ecc-tools.json @@ -0,0 +1,286 @@ +{ + "version": "1.3", + "schemaVersion": "1.0", + "generatedBy": "ecc-tools", + "generatedAt": "2026-07-29T00:47:07.692Z", + "repo": "https://github.com/diazMelgarejo/periscope", + "referenceSetReadiness": { + "score": 0, + "present": 0, + "total": 7, + "items": [ + { + "id": "deep-analyzer-corpus", + "label": "Deep analyzer corpus", + "status": "missing", + "evidence": [], + "recommendation": "Add analyzer fixture, golden, benchmark, or reference-set files that can catch analyzer regressions." + }, + { + "id": "rag-evaluator", + "label": "RAG/evaluator comparison", + "status": "missing", + "evidence": [], + "recommendation": "Add retrieval or evaluator reference-set comparison fixtures with expected ranking behavior." + }, + { + "id": "pr-salvage", + "label": "PR salvage/review corpus", + "status": "missing", + "evidence": [], + "recommendation": "Add stale-PR, review-thread, reopen-flow, or salvage reference cases for queue cleanup automation." + }, + { + "id": "discussion-triage", + "label": "Discussion triage corpus", + "status": "missing", + "evidence": [], + "recommendation": "Add public discussion triage fixtures, golden cases, or reference sets for informational, answered, and no-response classifications." + }, + { + "id": "harness-compatibility", + "label": "Harness compatibility", + "status": "missing", + "evidence": [], + "recommendation": "Add cross-harness, adapter-compliance, or harness-audit evidence for Claude, Codex, OpenCode, Zed, dmux, and agent surfaces." + }, + { + "id": "security-evidence", + "label": "Security evidence", + "status": "missing", + "evidence": [], + "recommendation": "Attach security evidence such as SBOMs, SARIF, audit reports, or AgentShield evidence packs." + }, + { + "id": "ci-failure-mode", + "label": "CI failure-mode evidence", + "status": "missing", + "evidence": [], + "recommendation": "Add captured CI failure logs, dry-run fixtures, or troubleshooting docs for common workflow failure modes." + } + ] + }, + "profiles": { + "requested": "developer", + "recommended": "developer", + "effective": "developer", + "requestedAlias": "developer", + "recommendedAlias": "developer", + "effectiveAlias": "developer" + }, + "requestedProfile": "developer", + "profile": "developer", + "recommendedProfile": "developer", + "effectiveProfile": "developer", + "tier": "free", + "requestedComponents": [ + "repo-baseline", + "workflow-automation" + ], + "selectedComponents": [ + "repo-baseline", + "workflow-automation" + ], + "requestedAddComponents": [], + "requestedRemoveComponents": [], + "blockedRemovalComponents": [], + "tierFilteredComponents": [], + "requestedRootPackages": [ + "runtime-core", + "workflow-pack" + ], + "selectedRootPackages": [ + "runtime-core", + "workflow-pack" + ], + "requestedPackages": [ + "runtime-core", + "workflow-pack" + ], + "requestedAddPackages": [], + "requestedRemovePackages": [], + "selectedPackages": [ + "runtime-core", + "workflow-pack" + ], + "packages": [ + "runtime-core", + "workflow-pack" + ], + "blockedRemovalPackages": [], + "tierFilteredRootPackages": [], + "tierFilteredPackages": [], + "conflictingPackages": [], + "dependencyGraph": { + "runtime-core": [], + "workflow-pack": [ + "runtime-core" + ] + }, + "resolutionOrder": [ + "runtime-core", + "workflow-pack" + ], + "requestedModules": [ + "runtime-core", + "workflow-pack" + ], + "selectedModules": [ + "runtime-core", + "workflow-pack" + ], + "modules": [ + "runtime-core", + "workflow-pack" + ], + "managedFiles": [ + ".claude/skills/periscope/SKILL.md", + ".agents/skills/periscope/SKILL.md", + ".agents/skills/periscope/agents/openai.yaml", + ".claude/identity.json", + ".codex/config.toml", + ".codex/AGENTS.md", + ".codex/agents/explorer.toml", + ".codex/agents/reviewer.toml", + ".codex/agents/docs-researcher.toml", + ".claude/homunculus/instincts/inherited/periscope-instincts.yaml", + ".claude/commands/add-or-update-database-feature.md", + ".claude/commands/add-new-parser-or-provider.md", + ".claude/commands/feature-development-with-tests-and-docs.md" + ], + "packageFiles": { + "runtime-core": [ + ".claude/skills/periscope/SKILL.md", + ".agents/skills/periscope/SKILL.md", + ".agents/skills/periscope/agents/openai.yaml", + ".claude/identity.json", + ".codex/config.toml", + ".codex/AGENTS.md", + ".codex/agents/explorer.toml", + ".codex/agents/reviewer.toml", + ".codex/agents/docs-researcher.toml", + ".claude/homunculus/instincts/inherited/periscope-instincts.yaml" + ], + "workflow-pack": [ + ".claude/commands/add-or-update-database-feature.md", + ".claude/commands/add-new-parser-or-provider.md", + ".claude/commands/feature-development-with-tests-and-docs.md" + ] + }, + "moduleFiles": { + "runtime-core": [ + ".claude/skills/periscope/SKILL.md", + ".agents/skills/periscope/SKILL.md", + ".agents/skills/periscope/agents/openai.yaml", + ".claude/identity.json", + ".codex/config.toml", + ".codex/AGENTS.md", + ".codex/agents/explorer.toml", + ".codex/agents/reviewer.toml", + ".codex/agents/docs-researcher.toml", + ".claude/homunculus/instincts/inherited/periscope-instincts.yaml" + ], + "workflow-pack": [ + ".claude/commands/add-or-update-database-feature.md", + ".claude/commands/add-new-parser-or-provider.md", + ".claude/commands/feature-development-with-tests-and-docs.md" + ] + }, + "files": [ + { + "moduleId": "runtime-core", + "path": ".claude/skills/periscope/SKILL.md", + "description": "Repository-specific Claude Code skill generated from git history." + }, + { + "moduleId": "runtime-core", + "path": ".agents/skills/periscope/SKILL.md", + "description": "Codex-facing copy of the generated repository skill." + }, + { + "moduleId": "runtime-core", + "path": ".agents/skills/periscope/agents/openai.yaml", + "description": "Codex skill metadata so the repo skill appears cleanly in the skill interface." + }, + { + "moduleId": "runtime-core", + "path": ".claude/identity.json", + "description": "Suggested identity.json baseline derived from repository conventions." + }, + { + "moduleId": "runtime-core", + "path": ".codex/config.toml", + "description": "Repo-local Codex MCP and multi-agent baseline aligned with ECC defaults." + }, + { + "moduleId": "runtime-core", + "path": ".codex/AGENTS.md", + "description": "Codex usage guide that points at the generated repo skill and workflow bundle." + }, + { + "moduleId": "runtime-core", + "path": ".codex/agents/explorer.toml", + "description": "Read-only explorer role config for Codex multi-agent work." + }, + { + "moduleId": "runtime-core", + "path": ".codex/agents/reviewer.toml", + "description": "Read-only reviewer role config focused on correctness and security." + }, + { + "moduleId": "runtime-core", + "path": ".codex/agents/docs-researcher.toml", + "description": "Read-only docs researcher role config for API verification." + }, + { + "moduleId": "runtime-core", + "path": ".claude/homunculus/instincts/inherited/periscope-instincts.yaml", + "description": "Continuous-learning instincts derived from repository patterns." + }, + { + "moduleId": "workflow-pack", + "path": ".claude/commands/add-or-update-database-feature.md", + "description": "Workflow command scaffold for add-or-update-database-feature." + }, + { + "moduleId": "workflow-pack", + "path": ".claude/commands/add-new-parser-or-provider.md", + "description": "Workflow command scaffold for add-new-parser-or-provider." + }, + { + "moduleId": "workflow-pack", + "path": ".claude/commands/feature-development-with-tests-and-docs.md", + "description": "Workflow command scaffold for feature-development-with-tests-and-docs." + } + ], + "workflows": [ + { + "command": "add-or-update-database-feature", + "path": ".claude/commands/add-or-update-database-feature.md" + }, + { + "command": "add-new-parser-or-provider", + "path": ".claude/commands/add-new-parser-or-provider.md" + }, + { + "command": "feature-development-with-tests-and-docs", + "path": ".claude/commands/feature-development-with-tests-and-docs.md" + } + ], + "adapters": { + "claudeCode": { + "skillPath": ".claude/skills/periscope/SKILL.md", + "identityPath": ".claude/identity.json", + "commandPaths": [ + ".claude/commands/add-or-update-database-feature.md", + ".claude/commands/add-new-parser-or-provider.md", + ".claude/commands/feature-development-with-tests-and-docs.md" + ] + }, + "codex": { + "configPath": ".codex/config.toml", + "agentsGuidePath": ".codex/AGENTS.md", + "skillPath": ".agents/skills/periscope/SKILL.md" + } + } +} \ No newline at end of file From 7234413061865284465a27f93f1fd952d5d48999 Mon Sep 17 00:00:00 2001 From: "ecc-tools[bot]" <257055122+ecc-tools[bot]@users.noreply.github.com> Date: Wed, 29 Jul 2026 00:47:37 +0000 Subject: [PATCH 02/14] feat: add periscope ECC bundle (.claude/skills/periscope/SKILL.md) --- .claude/skills/periscope/SKILL.md | 162 ++++++++++++++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 .claude/skills/periscope/SKILL.md diff --git a/.claude/skills/periscope/SKILL.md b/.claude/skills/periscope/SKILL.md new file mode 100644 index 000000000..04bf2baa8 --- /dev/null +++ b/.claude/skills/periscope/SKILL.md @@ -0,0 +1,162 @@ +```markdown +# periscope Development Patterns + +> Auto-generated skill from repository analysis + +## Overview + +This skill teaches you the core development patterns, coding conventions, and workflows used in the `periscope` Go codebase. You'll learn how to add new database features, implement new parsers/providers, and develop features with proper tests and documentation. The guide covers file organization, code style, and step-by-step instructions for common contribution workflows. + +--- + +## Coding Conventions + +**File Naming** +- Use `snake_case` for file names. + - Example: `session_parser.go`, `db_utils.go` + +**Imports** +- Use absolute import paths. + - Example: + ```go + import "github.com/yourorg/periscope/internal/db" + ``` + +**Exports** +- Use named exports for functions, types, and variables. + - Example: + ```go + // Exported function + func NewSessionParser() *SessionParser { + // ... + } + ``` + +**Commit Messages** +- Prefix with `fix:` or `feat:` +- Keep messages concise (~54 characters on average) + - Example: `feat: add support for new agent provider` + +--- + +## Workflows + +### Add or Update Database Feature +**Trigger:** When adding a new database-backed feature or modifying database structure/logic +**Command:** `/new-table` + +1. Edit or add SQL schema files (e.g., `internal/db/schema.sql`). +2. Update Go code for database access and logic (e.g., `internal/db/*.go`). +3. Add or update trigger DDL and migration logic in Go (e.g., `internal/db/db.go`). +4. Write or update tests for new/changed database logic (e.g., `internal/db/*_test.go`, `cmd/agentsview/*_test.go`). +5. Update or add documentation/specs if the feature is significant (e.g., `docs/superpowers/specs/...`). + +**Example:** +```sql +-- internal/db/schema.sql +ALTER TABLE sessions ADD COLUMN agent_version TEXT; +``` +```go +// internal/db/session.go +func (db *DB) AddAgentVersion(sessionID int, version string) error { + // implementation +} +``` +```go +// internal/db/session_test.go +func TestAddAgentVersion(t *testing.T) { + // test logic +} +``` + +--- + +### Add New Parser or Provider +**Trigger:** When supporting a new agent or data format +**Command:** `/add-parser` + +1. Add new parser/provider Go files (e.g., `internal/parser/_provider.go`, `internal/parser/.go`). +2. Update provider registry or discovery (e.g., `internal/parser/provider.go`). +3. Add or update test data and test cases (e.g., `internal/parser/testdata//*.json`, `internal/parser/_test.go`). +4. Integrate with sync engine if needed (e.g., `internal/sync/engine.go`). +5. Update documentation and format sources (e.g., `docs/internal/session-format-sources.md`, `docs/configuration.md`). +6. Update frontend agent lists if surfaced (e.g., `frontend/src/lib/utils/agents.ts`). + +**Example:** +```go +// internal/parser/myagent_provider.go +type MyAgentProvider struct { /* ... */ } +func (p *MyAgentProvider) Parse(data []byte) (*Session, error) { /* ... */ } +``` +```go +// internal/parser/provider.go +func init() { + RegisterProvider("myagent", &MyAgentProvider{}) +} +``` +```json +// internal/parser/testdata/myagent/sample.json +{ "session_id": 123, "agent": "myagent", ... } +``` + +--- + +### Feature Development with Tests and Docs +**Trigger:** When developing a new feature or major enhancement +**Command:** `/feature` + +1. Implement feature in Go (e.g., `internal//*.go`). +2. Write or update tests (e.g., `internal//*_test.go`, `cmd/agentsview/*_test.go`). +3. Update or add documentation/specs (e.g., `docs/superpowers/specs/*.md`, `docs/configuration.md`). +4. Update frontend if feature is user-facing (e.g., `frontend/src/lib/utils/agents.ts`). + +**Example:** +```go +// internal/feature/awesome.go +func EnableAwesomeFeature() error { + // feature logic +} +``` +```go +// internal/feature/awesome_test.go +func TestEnableAwesomeFeature(t *testing.T) { + // test logic +} +``` +```markdown + +# Awesome Feature Spec +... +``` + +--- + +## Testing Patterns + +- Test files use the pattern `*_test.go`. +- Tests are written using Go's standard `testing` package. +- Test data may be stored in `testdata` directories, often as JSON files for parsers. +- Example test file: + ```go + // internal/parser/myagent_test.go + func TestMyAgentParser(t *testing.T) { + // Arrange + data, _ := ioutil.ReadFile("testdata/myagent/sample.json") + // Act + session, err := MyAgentProvider{}.Parse(data) + // Assert + if err != nil { t.Fatal(err) } + // Additional assertions... + } + ``` + +--- + +## Commands + +| Command | Purpose | +|--------------|----------------------------------------------------------------| +| /new-table | Add or update a database-backed feature or schema | +| /add-parser | Add support for a new agent/provider/parser | +| /feature | Implement a new feature or significant enhancement with tests | +``` From a1475e43a1f3fa832903c7b4dd8393e5a39e724c Mon Sep 17 00:00:00 2001 From: "ecc-tools[bot]" <257055122+ecc-tools[bot]@users.noreply.github.com> Date: Wed, 29 Jul 2026 00:47:38 +0000 Subject: [PATCH 03/14] feat: add periscope ECC bundle (.agents/skills/periscope/SKILL.md) --- .agents/skills/periscope/SKILL.md | 162 ++++++++++++++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 .agents/skills/periscope/SKILL.md diff --git a/.agents/skills/periscope/SKILL.md b/.agents/skills/periscope/SKILL.md new file mode 100644 index 000000000..04bf2baa8 --- /dev/null +++ b/.agents/skills/periscope/SKILL.md @@ -0,0 +1,162 @@ +```markdown +# periscope Development Patterns + +> Auto-generated skill from repository analysis + +## Overview + +This skill teaches you the core development patterns, coding conventions, and workflows used in the `periscope` Go codebase. You'll learn how to add new database features, implement new parsers/providers, and develop features with proper tests and documentation. The guide covers file organization, code style, and step-by-step instructions for common contribution workflows. + +--- + +## Coding Conventions + +**File Naming** +- Use `snake_case` for file names. + - Example: `session_parser.go`, `db_utils.go` + +**Imports** +- Use absolute import paths. + - Example: + ```go + import "github.com/yourorg/periscope/internal/db" + ``` + +**Exports** +- Use named exports for functions, types, and variables. + - Example: + ```go + // Exported function + func NewSessionParser() *SessionParser { + // ... + } + ``` + +**Commit Messages** +- Prefix with `fix:` or `feat:` +- Keep messages concise (~54 characters on average) + - Example: `feat: add support for new agent provider` + +--- + +## Workflows + +### Add or Update Database Feature +**Trigger:** When adding a new database-backed feature or modifying database structure/logic +**Command:** `/new-table` + +1. Edit or add SQL schema files (e.g., `internal/db/schema.sql`). +2. Update Go code for database access and logic (e.g., `internal/db/*.go`). +3. Add or update trigger DDL and migration logic in Go (e.g., `internal/db/db.go`). +4. Write or update tests for new/changed database logic (e.g., `internal/db/*_test.go`, `cmd/agentsview/*_test.go`). +5. Update or add documentation/specs if the feature is significant (e.g., `docs/superpowers/specs/...`). + +**Example:** +```sql +-- internal/db/schema.sql +ALTER TABLE sessions ADD COLUMN agent_version TEXT; +``` +```go +// internal/db/session.go +func (db *DB) AddAgentVersion(sessionID int, version string) error { + // implementation +} +``` +```go +// internal/db/session_test.go +func TestAddAgentVersion(t *testing.T) { + // test logic +} +``` + +--- + +### Add New Parser or Provider +**Trigger:** When supporting a new agent or data format +**Command:** `/add-parser` + +1. Add new parser/provider Go files (e.g., `internal/parser/_provider.go`, `internal/parser/.go`). +2. Update provider registry or discovery (e.g., `internal/parser/provider.go`). +3. Add or update test data and test cases (e.g., `internal/parser/testdata//*.json`, `internal/parser/_test.go`). +4. Integrate with sync engine if needed (e.g., `internal/sync/engine.go`). +5. Update documentation and format sources (e.g., `docs/internal/session-format-sources.md`, `docs/configuration.md`). +6. Update frontend agent lists if surfaced (e.g., `frontend/src/lib/utils/agents.ts`). + +**Example:** +```go +// internal/parser/myagent_provider.go +type MyAgentProvider struct { /* ... */ } +func (p *MyAgentProvider) Parse(data []byte) (*Session, error) { /* ... */ } +``` +```go +// internal/parser/provider.go +func init() { + RegisterProvider("myagent", &MyAgentProvider{}) +} +``` +```json +// internal/parser/testdata/myagent/sample.json +{ "session_id": 123, "agent": "myagent", ... } +``` + +--- + +### Feature Development with Tests and Docs +**Trigger:** When developing a new feature or major enhancement +**Command:** `/feature` + +1. Implement feature in Go (e.g., `internal//*.go`). +2. Write or update tests (e.g., `internal//*_test.go`, `cmd/agentsview/*_test.go`). +3. Update or add documentation/specs (e.g., `docs/superpowers/specs/*.md`, `docs/configuration.md`). +4. Update frontend if feature is user-facing (e.g., `frontend/src/lib/utils/agents.ts`). + +**Example:** +```go +// internal/feature/awesome.go +func EnableAwesomeFeature() error { + // feature logic +} +``` +```go +// internal/feature/awesome_test.go +func TestEnableAwesomeFeature(t *testing.T) { + // test logic +} +``` +```markdown + +# Awesome Feature Spec +... +``` + +--- + +## Testing Patterns + +- Test files use the pattern `*_test.go`. +- Tests are written using Go's standard `testing` package. +- Test data may be stored in `testdata` directories, often as JSON files for parsers. +- Example test file: + ```go + // internal/parser/myagent_test.go + func TestMyAgentParser(t *testing.T) { + // Arrange + data, _ := ioutil.ReadFile("testdata/myagent/sample.json") + // Act + session, err := MyAgentProvider{}.Parse(data) + // Assert + if err != nil { t.Fatal(err) } + // Additional assertions... + } + ``` + +--- + +## Commands + +| Command | Purpose | +|--------------|----------------------------------------------------------------| +| /new-table | Add or update a database-backed feature or schema | +| /add-parser | Add support for a new agent/provider/parser | +| /feature | Implement a new feature or significant enhancement with tests | +``` From 82ab231550ed1fa8073cc94f8d53d1343c1f60a3 Mon Sep 17 00:00:00 2001 From: "ecc-tools[bot]" <257055122+ecc-tools[bot]@users.noreply.github.com> Date: Wed, 29 Jul 2026 00:47:39 +0000 Subject: [PATCH 04/14] feat: add periscope ECC bundle (.agents/skills/periscope/agents/openai.yaml) --- .agents/skills/periscope/agents/openai.yaml | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 .agents/skills/periscope/agents/openai.yaml diff --git a/.agents/skills/periscope/agents/openai.yaml b/.agents/skills/periscope/agents/openai.yaml new file mode 100644 index 000000000..49cec3212 --- /dev/null +++ b/.agents/skills/periscope/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: "Periscope" + short_description: "Repo-specific patterns and workflows for periscope" + default_prompt: "Use the periscope repo skill to follow existing architecture, testing, and workflow conventions." +policy: + allow_implicit_invocation: true \ No newline at end of file From 3e46798718a54f1f50d9c1674252a3651d77210b Mon Sep 17 00:00:00 2001 From: "ecc-tools[bot]" <257055122+ecc-tools[bot]@users.noreply.github.com> Date: Wed, 29 Jul 2026 00:47:40 +0000 Subject: [PATCH 05/14] feat: add periscope ECC bundle (.claude/identity.json) --- .claude/identity.json | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 .claude/identity.json diff --git a/.claude/identity.json b/.claude/identity.json new file mode 100644 index 000000000..b432fb2eb --- /dev/null +++ b/.claude/identity.json @@ -0,0 +1,14 @@ +{ + "version": "2.0", + "technicalLevel": "technical", + "preferredStyle": { + "verbosity": "moderate", + "codeComments": true, + "explanations": true + }, + "domains": [ + "go" + ], + "suggestedBy": "ecc-tools-repo-analysis", + "createdAt": "2026-07-29T00:47:29.674Z" +} \ No newline at end of file From 245931325f9a1ad6ee3f12f9b8148bf92e4e2f2c Mon Sep 17 00:00:00 2001 From: "ecc-tools[bot]" <257055122+ecc-tools[bot]@users.noreply.github.com> Date: Wed, 29 Jul 2026 00:47:41 +0000 Subject: [PATCH 06/14] feat: add periscope ECC bundle (.codex/config.toml) --- .codex/config.toml | 48 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 .codex/config.toml diff --git a/.codex/config.toml b/.codex/config.toml new file mode 100644 index 000000000..bc1ee67f6 --- /dev/null +++ b/.codex/config.toml @@ -0,0 +1,48 @@ +#:schema https://developers.openai.com/codex/config-schema.json + +# ECC Tools generated Codex baseline +approval_policy = "on-request" +sandbox_mode = "workspace-write" +web_search = "live" + +[mcp_servers.github] +command = "npx" +args = ["-y", "@modelcontextprotocol/server-github"] + +[mcp_servers.context7] +command = "npx" +args = ["-y", "@upstash/context7-mcp@latest"] + +[mcp_servers.exa] +url = "https://mcp.exa.ai/mcp" + +[mcp_servers.memory] +command = "npx" +args = ["-y", "@modelcontextprotocol/server-memory"] + +[mcp_servers.playwright] +command = "npx" +args = ["-y", "@playwright/mcp@latest", "--extension"] + +[mcp_servers.sequential-thinking] +command = "npx" +args = ["-y", "@modelcontextprotocol/server-sequential-thinking"] + +[features] +multi_agent = true + +[agents] +max_threads = 6 +max_depth = 1 + +[agents.explorer] +description = "Read-only codebase explorer for gathering evidence before changes are proposed." +config_file = "agents/explorer.toml" + +[agents.reviewer] +description = "PR reviewer focused on correctness, security, and missing tests." +config_file = "agents/reviewer.toml" + +[agents.docs_researcher] +description = "Documentation specialist that verifies APIs, framework behavior, and release notes." +config_file = "agents/docs-researcher.toml" \ No newline at end of file From 8c64cdff7a3c753b85765df82e0caf209afa3858 Mon Sep 17 00:00:00 2001 From: "ecc-tools[bot]" <257055122+ecc-tools[bot]@users.noreply.github.com> Date: Wed, 29 Jul 2026 00:47:42 +0000 Subject: [PATCH 07/14] feat: add periscope ECC bundle (.codex/AGENTS.md) --- .codex/AGENTS.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 .codex/AGENTS.md diff --git a/.codex/AGENTS.md b/.codex/AGENTS.md new file mode 100644 index 000000000..f281b5055 --- /dev/null +++ b/.codex/AGENTS.md @@ -0,0 +1,28 @@ +# ECC for Codex CLI + +This supplements the root `AGENTS.md` with a repo-local ECC baseline. + +## Repo Skill + +- Repo-generated Codex skill: `.agents/skills/periscope/SKILL.md` +- Claude-facing companion skill: `.claude/skills/periscope/SKILL.md` +- Keep user-specific credentials and private MCPs in `~/.codex/config.toml`, not in this repo. + +## MCP Baseline + +Treat `.codex/config.toml` as the default ECC-safe baseline for work in this repository. +The generated baseline enables GitHub, Context7, Exa, Memory, Playwright, and Sequential Thinking. + +## Multi-Agent Support + +- Explorer: read-only evidence gathering +- Reviewer: correctness, security, and regression review +- Docs researcher: API and release-note verification + +## Workflow Files + +- `.claude/commands/add-or-update-database-feature.md` +- `.claude/commands/add-new-parser-or-provider.md` +- `.claude/commands/feature-development-with-tests-and-docs.md` + +Use these workflow files as reusable task scaffolds when the detected repository workflows recur. \ No newline at end of file From 0a1cb2a51eccbb5cb8a69c7889e98a38cddcc010 Mon Sep 17 00:00:00 2001 From: "ecc-tools[bot]" <257055122+ecc-tools[bot]@users.noreply.github.com> Date: Wed, 29 Jul 2026 00:47:43 +0000 Subject: [PATCH 08/14] feat: add periscope ECC bundle (.codex/agents/explorer.toml) --- .codex/agents/explorer.toml | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 .codex/agents/explorer.toml diff --git a/.codex/agents/explorer.toml b/.codex/agents/explorer.toml new file mode 100644 index 000000000..732df7aff --- /dev/null +++ b/.codex/agents/explorer.toml @@ -0,0 +1,9 @@ +model = "gpt-5.4" +model_reasoning_effort = "medium" +sandbox_mode = "read-only" + +developer_instructions = """ +Stay in exploration mode. +Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them. +Prefer targeted search and file reads over broad scans. +""" \ No newline at end of file From e4863407505dcfe34b194d16214faea306deb579 Mon Sep 17 00:00:00 2001 From: "ecc-tools[bot]" <257055122+ecc-tools[bot]@users.noreply.github.com> Date: Wed, 29 Jul 2026 00:47:45 +0000 Subject: [PATCH 09/14] feat: add periscope ECC bundle (.codex/agents/reviewer.toml) --- .codex/agents/reviewer.toml | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 .codex/agents/reviewer.toml diff --git a/.codex/agents/reviewer.toml b/.codex/agents/reviewer.toml new file mode 100644 index 000000000..b13ed9cf1 --- /dev/null +++ b/.codex/agents/reviewer.toml @@ -0,0 +1,9 @@ +model = "gpt-5.4" +model_reasoning_effort = "high" +sandbox_mode = "read-only" + +developer_instructions = """ +Review like an owner. +Prioritize correctness, security, behavioral regressions, and missing tests. +Lead with concrete findings and avoid style-only feedback unless it hides a real bug. +""" \ No newline at end of file From 3ad25b2e492b617af18787b2348ce72f42cdd8f5 Mon Sep 17 00:00:00 2001 From: "ecc-tools[bot]" <257055122+ecc-tools[bot]@users.noreply.github.com> Date: Wed, 29 Jul 2026 00:47:46 +0000 Subject: [PATCH 10/14] feat: add periscope ECC bundle (.codex/agents/docs-researcher.toml) --- .codex/agents/docs-researcher.toml | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 .codex/agents/docs-researcher.toml diff --git a/.codex/agents/docs-researcher.toml b/.codex/agents/docs-researcher.toml new file mode 100644 index 000000000..0daae570b --- /dev/null +++ b/.codex/agents/docs-researcher.toml @@ -0,0 +1,9 @@ +model = "gpt-5.4" +model_reasoning_effort = "medium" +sandbox_mode = "read-only" + +developer_instructions = """ +Verify APIs, framework behavior, and release-note claims against primary documentation before changes land. +Cite the exact docs or file paths that support each claim. +Do not invent undocumented behavior. +""" \ No newline at end of file From 419ff6d976750fac84dad73c29ab15fefdb6466c Mon Sep 17 00:00:00 2001 From: "ecc-tools[bot]" <257055122+ecc-tools[bot]@users.noreply.github.com> Date: Wed, 29 Jul 2026 00:47:47 +0000 Subject: [PATCH 11/14] feat: add periscope ECC bundle (.claude/homunculus/instincts/inherited/periscope-instincts.yaml) --- .../inherited/periscope-instincts.yaml | 439 ++++++++++++++++++ 1 file changed, 439 insertions(+) create mode 100644 .claude/homunculus/instincts/inherited/periscope-instincts.yaml diff --git a/.claude/homunculus/instincts/inherited/periscope-instincts.yaml b/.claude/homunculus/instincts/inherited/periscope-instincts.yaml new file mode 100644 index 000000000..d202a55b2 --- /dev/null +++ b/.claude/homunculus/instincts/inherited/periscope-instincts.yaml @@ -0,0 +1,439 @@ +# Instincts generated from https://github.com/diazMelgarejo/periscope +# Generated: 2026-07-29T00:47:29.674Z +# Version: 2.0 +# NOTE: This file supplements (does not replace) any existing curated instincts. +# High-confidence manually curated instincts should be preserved alongside these. + +--- +id: periscope-commit-length +trigger: "when writing a commit message" +confidence: 0.6 +domain: git +source: repo-analysis +source_repo: https://github.com/diazMelgarejo/periscope +--- + +# Periscope Commit Length + +## Action + +Write moderate-length commit messages (~54 characters) + +## Evidence + +- Average commit message length: 54 chars +- Based on 3 commits + +--- +id: periscope-naming-files +trigger: "when creating a new file" +confidence: 0.8 +domain: code-style +source: repo-analysis +source_repo: https://github.com/diazMelgarejo/periscope +--- + +# Periscope Naming Files + +## Action + +Use snake_case naming convention + +## Evidence + +- Analyzed file naming patterns in repository +- Dominant pattern: snake_case + +--- +id: periscope-export-style +trigger: "when exporting from a module" +confidence: 0.7 +domain: code-style +source: repo-analysis +source_repo: https://github.com/diazMelgarejo/periscope +--- + +# Periscope Export Style + +## Action + +Prefer named exports + +## Evidence + +- Export pattern analysis +- Dominant style: named + +--- +id: periscope-arch-type-based +trigger: "when adding new code" +confidence: 0.8 +domain: architecture +source: repo-analysis +source_repo: https://github.com/diazMelgarejo/periscope +--- + +# Periscope Arch Type Based + +## Action + +Place code in the appropriate type folder (components/, services/, utils/, etc.) + +## Evidence + +- Type-based module organization detected +- Folders: + +--- +id: periscope-workflow-add-or-update-database-feature +trigger: "when doing add or update database feature" +confidence: 0.55 +domain: workflow +source: repo-analysis +source_repo: https://github.com/diazMelgarejo/periscope +--- + +# Periscope Workflow Add Or Update Database Feature + +## Action + +Follow the add-or-update-database-feature workflow: +1. Edit or add SQL schema files (e.g., internal/db/schema.sql). +2. Update Go code for database access and logic (e.g., internal/db/*.go). +3. Add or update trigger DDL and migration logic in Go (e.g., internal/db/db.go). +4. Write or update tests for new/changed database logic (e.g., internal/db/*_test.go, cmd/agentsview/*_test.go). +5. Update or add documentation/specs if the feature is significant (e.g., docs/superpowers/specs/...). + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~1x per month +- Files: internal/db/schema.sql, internal/db/*.go, internal/db/*_test.go + +--- +id: periscope-workflow-add-new-parser-or-provider +trigger: "when doing add new parser or provider" +confidence: 0.55 +domain: workflow +source: repo-analysis +source_repo: https://github.com/diazMelgarejo/periscope +--- + +# Periscope Workflow Add New Parser Or Provider + +## Action + +Follow the add-new-parser-or-provider workflow: +1. Add new parser/provider Go files (e.g., internal/parser/_provider.go, internal/parser/.go). +2. Update provider registry or discovery (e.g., internal/parser/provider.go). +3. Add or update test data and test cases (e.g., internal/parser/testdata//*.json, internal/parser/_test.go). +4. Integrate with sync engine if needed (e.g., internal/sync/engine.go). +5. Update documentation and format sources (e.g., docs/internal/session-format-sources.md, docs/configuration.md). +6. Update frontend agent lists if surfaced (e.g., frontend/src/lib/utils/agents.ts). + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~1x per month +- Files: internal/parser/*_provider.go, internal/parser/*.go, internal/parser/testdata/*/*.json + +--- +id: periscope-workflow-feature-development-with-tests-and-docs +trigger: "when doing feature development with tests and docs" +confidence: 0.6 +domain: workflow +source: repo-analysis +source_repo: https://github.com/diazMelgarejo/periscope +--- + +# Periscope Workflow Feature Development With Tests And Docs + +## Action + +Follow the feature-development-with-tests-and-docs workflow: +1. Implement feature in Go (e.g., internal//*.go). +2. Write or update tests (e.g., internal//*_test.go, cmd/agentsview/*_test.go). +3. Update or add documentation/specs (e.g., docs/superpowers/specs/*.md, docs/configuration.md). +4. Update frontend if feature is user-facing (e.g., frontend/src/lib/utils/agents.ts). + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~2x per month +- Files: internal/*/*.go, internal/*/*_test.go, cmd/agentsview/*_test.go + +--- +id: periscope-instinct-file-naming +trigger: "When creating or renaming a file in the codebase" +confidence: 0.9 +domain: code-style +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct File Naming + +## Action + +Use snake_case for file names + +## Evidence + +- Pattern in file names across internal/, cmd/, and frontend/ folders + +--- +id: periscope-instinct-function-naming +trigger: "When defining a function in Go code" +confidence: 0.9 +domain: code-style +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Function Naming + +## Action + +Use camelCase for function names + +## Evidence + +- Pattern in Go source files in internal/ and cmd/ +- Go language convention + +--- +id: periscope-instinct-class-naming +trigger: "When defining a struct or type that acts as a class in Go" +confidence: 0.9 +domain: code-style +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Class Naming + +## Action + +Use PascalCase for struct/type names + +## Evidence + +- Pattern in Go source files in internal/ and cmd/ + +--- +id: periscope-instinct-constant-naming +trigger: "When declaring a constant in Go code" +confidence: 0.8 +domain: code-style +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Constant Naming + +## Action + +Use SCREAMING_SNAKE_CASE for constant names + +## Evidence + +- Pattern in Go source files in internal/ + +--- +id: periscope-instinct-import-style +trigger: "When importing modules in Go code" +confidence: 0.85 +domain: code-style +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Import Style + +## Action + +Use absolute import paths + +## Evidence + +- Pattern in Go source files in internal/ and cmd/ + +--- +id: periscope-instinct-export-style +trigger: "When exporting functions/types in Go code" +confidence: 0.8 +domain: code-style +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Export Style + +## Action + +Use named exports (export only what is needed, using capitalized names) + +## Evidence + +- Pattern in Go source files in internal/ and cmd/ + +--- +id: periscope-instinct-test-location +trigger: "When writing tests for Go code" +confidence: 0.9 +domain: testing +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Test Location + +## Action + +Place test files alongside implementation files, using *_test.go suffix + +## Evidence + +- Pattern in internal/*/*_test.go +- cmd/agentsview/*_test.go + +--- +id: periscope-instinct-test-coverage +trigger: "When adding or modifying a feature" +confidence: 0.9 +domain: testing +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Test Coverage + +## Action + +Write or update corresponding *_test.go files to cover new/changed logic + +## Evidence + +- Workflow commit sequences for all workflows +- Pattern in internal/*/*_test.go + +--- +id: periscope-instinct-testdata-usage +trigger: "When adding a new parser/provider" +confidence: 0.85 +domain: testing +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Testdata Usage + +## Action + +Add or update test data in internal/parser/testdata//*.json + +## Evidence + +- Workflow: add-new-parser-or-provider +- Pattern in internal/parser/testdata/ + +--- +id: periscope-instinct-git-commit-prefix +trigger: "When writing a commit message" +confidence: 0.9 +domain: git +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Git Commit Prefix + +## Action + +Prefix the message with fix or feat (or similar), followed by the scope in parentheses and a brief description + +## Evidence + +- fix(cli): expand leading tilde in DuckDB mirror paths (#1274) +- feat(parser): add Omnigent support (#1284) + +--- +id: periscope-instinct-git-commit-length +trigger: "When writing a commit message" +confidence: 0.8 +domain: git +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Git Commit Length + +## Action + +Keep the commit message concise (average length ~54 characters) + +## Evidence + +- Average commit message length: 54 +- Examples in commit history + +--- +id: periscope-instinct-add-or-update-database-feature +trigger: "When adding or updating a database-backed feature or modifying database structure/logic" +confidence: 0.9 +domain: workflow +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Add Or Update Database Feature + +## Action + +Edit SQL schema, update Go database logic, add migration logic, write tests, and update docs/specs as needed + +## Evidence + +- Workflow: add-or-update-database-feature +- Pattern in files: internal/db/schema.sql, internal/db/*.go, internal/db/*_test.go, docs/superpowers/specs/*.md + +--- +id: periscope-instinct-add-new-parser-or-provider +trigger: "When adding support for a new agent, provider, or parser" +confidence: 0.85 +domain: workflow +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Add New Parser Or Provider + +## Action + +Add new provider Go files, update registry, add test data/cases, integrate with sync engine, update docs and frontend if needed + +## Evidence + +- Workflow: add-new-parser-or-provider +- Pattern in files: internal/parser/*_provider.go, internal/parser/testdata/*/*.json, frontend/src/lib/utils/agents.ts + +--- +id: periscope-instinct-feature-development-with-tests-and-docs +trigger: "When developing a new feature or significant enhancement" +confidence: 0.85 +domain: workflow +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Feature Development With Tests And Docs + +## Action + +Implement feature in Go, write/update tests, update/add documentation/specs, and update frontend if user-facing + +## Evidence + +- Workflow: feature-development-with-tests-and-docs +- Pattern in files: internal/*/*.go, internal/*/*_test.go, docs/superpowers/specs/*.md, frontend/src/lib/utils/agents.ts + From ac9a5e4148cd2c4c38dd9d0e23b9f2f50157bbfc Mon Sep 17 00:00:00 2001 From: "ecc-tools[bot]" <257055122+ecc-tools[bot]@users.noreply.github.com> Date: Wed, 29 Jul 2026 00:47:48 +0000 Subject: [PATCH 12/14] feat: add periscope ECC bundle (.claude/commands/add-or-update-database-feature.md) --- .../add-or-update-database-feature.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 .claude/commands/add-or-update-database-feature.md diff --git a/.claude/commands/add-or-update-database-feature.md b/.claude/commands/add-or-update-database-feature.md new file mode 100644 index 000000000..98b6f9d82 --- /dev/null +++ b/.claude/commands/add-or-update-database-feature.md @@ -0,0 +1,41 @@ +--- +name: add-or-update-database-feature +description: Workflow command scaffold for add-or-update-database-feature in periscope. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /add-or-update-database-feature + +Use this workflow when working on **add-or-update-database-feature** in `periscope`. + +## Goal + +Implements a new database-backed feature or updates existing database logic, including schema changes, new tables, triggers, and related Go logic. + +## Common Files + +- `internal/db/schema.sql` +- `internal/db/*.go` +- `internal/db/*_test.go` +- `cmd/agentsview/*_test.go` +- `docs/superpowers/specs/*.md` + +## Suggested Sequence + +1. Understand the current state and failure mode before editing. +2. Make the smallest coherent change that satisfies the workflow goal. +3. Run the most relevant verification for touched files. +4. Summarize what changed and what still needs review. + +## Typical Commit Signals + +- Edit or add SQL schema files (e.g., internal/db/schema.sql). +- Update Go code for database access and logic (e.g., internal/db/*.go). +- Add or update trigger DDL and migration logic in Go (e.g., internal/db/db.go). +- Write or update tests for new/changed database logic (e.g., internal/db/*_test.go, cmd/agentsview/*_test.go). +- Update or add documentation/specs if the feature is significant (e.g., docs/superpowers/specs/...). + +## Notes + +- Treat this as a scaffold, not a hard-coded script. +- Update the command if the workflow evolves materially. \ No newline at end of file From 99d2933d9626eebf23cf56672977f128733d4193 Mon Sep 17 00:00:00 2001 From: "ecc-tools[bot]" <257055122+ecc-tools[bot]@users.noreply.github.com> Date: Wed, 29 Jul 2026 00:47:49 +0000 Subject: [PATCH 13/14] feat: add periscope ECC bundle (.claude/commands/add-new-parser-or-provider.md) --- .../commands/add-new-parser-or-provider.md | 42 +++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 .claude/commands/add-new-parser-or-provider.md diff --git a/.claude/commands/add-new-parser-or-provider.md b/.claude/commands/add-new-parser-or-provider.md new file mode 100644 index 000000000..9acbce737 --- /dev/null +++ b/.claude/commands/add-new-parser-or-provider.md @@ -0,0 +1,42 @@ +--- +name: add-new-parser-or-provider +description: Workflow command scaffold for add-new-parser-or-provider in periscope. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /add-new-parser-or-provider + +Use this workflow when working on **add-new-parser-or-provider** in `periscope`. + +## Goal + +Adds support for a new agent/provider/parser, including implementation, integration, and test coverage. + +## Common Files + +- `internal/parser/*_provider.go` +- `internal/parser/*.go` +- `internal/parser/testdata/*/*.json` +- `internal/parser/*_test.go` +- `internal/parser/provider.go` +- `internal/sync/engine.go` + +## Suggested Sequence + +1. Understand the current state and failure mode before editing. +2. Make the smallest coherent change that satisfies the workflow goal. +3. Run the most relevant verification for touched files. +4. Summarize what changed and what still needs review. + +## Typical Commit Signals + +- Add new parser/provider Go files (e.g., internal/parser/_provider.go, internal/parser/.go). +- Update provider registry or discovery (e.g., internal/parser/provider.go). +- Add or update test data and test cases (e.g., internal/parser/testdata//*.json, internal/parser/_test.go). +- Integrate with sync engine if needed (e.g., internal/sync/engine.go). +- Update documentation and format sources (e.g., docs/internal/session-format-sources.md, docs/configuration.md). + +## Notes + +- Treat this as a scaffold, not a hard-coded script. +- Update the command if the workflow evolves materially. \ No newline at end of file From 81f295316026d85e964013d99eeb0bb7b03a62e3 Mon Sep 17 00:00:00 2001 From: "ecc-tools[bot]" <257055122+ecc-tools[bot]@users.noreply.github.com> Date: Wed, 29 Jul 2026 00:47:50 +0000 Subject: [PATCH 14/14] feat: add periscope ECC bundle (.claude/commands/feature-development-with-tests-and-docs.md) --- ...feature-development-with-tests-and-docs.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 .claude/commands/feature-development-with-tests-and-docs.md diff --git a/.claude/commands/feature-development-with-tests-and-docs.md b/.claude/commands/feature-development-with-tests-and-docs.md new file mode 100644 index 000000000..67ef25250 --- /dev/null +++ b/.claude/commands/feature-development-with-tests-and-docs.md @@ -0,0 +1,41 @@ +--- +name: feature-development-with-tests-and-docs +description: Workflow command scaffold for feature-development-with-tests-and-docs in periscope. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /feature-development-with-tests-and-docs + +Use this workflow when working on **feature-development-with-tests-and-docs** in `periscope`. + +## Goal + +Implements a new feature or significant enhancement, accompanied by tests and documentation/specs. + +## Common Files + +- `internal/*/*.go` +- `internal/*/*_test.go` +- `cmd/agentsview/*_test.go` +- `docs/superpowers/specs/*.md` +- `docs/configuration.md` +- `frontend/src/lib/utils/agents.ts` + +## Suggested Sequence + +1. Understand the current state and failure mode before editing. +2. Make the smallest coherent change that satisfies the workflow goal. +3. Run the most relevant verification for touched files. +4. Summarize what changed and what still needs review. + +## Typical Commit Signals + +- Implement feature in Go (e.g., internal//*.go). +- Write or update tests (e.g., internal//*_test.go, cmd/agentsview/*_test.go). +- Update or add documentation/specs (e.g., docs/superpowers/specs/*.md, docs/configuration.md). +- Update frontend if feature is user-facing (e.g., frontend/src/lib/utils/agents.ts). + +## Notes + +- Treat this as a scaffold, not a hard-coded script. +- Update the command if the workflow evolves materially. \ No newline at end of file