diff --git a/.agents/skills/periscope/SKILL.md b/.agents/skills/periscope/SKILL.md index ba8c5fa5d..83661ceb0 100644 --- a/.agents/skills/periscope/SKILL.md +++ b/.agents/skills/periscope/SKILL.md @@ -1,7 +1,8 @@ # periscope Development Patterns -> Synthesized from two ECC repository-analysis runs and verified against the -> repository's documented architecture and test layout. +> Synthesized from ECC repository-analysis runs (PR #16 harmonization + PR #18 +> additive replay) and verified against the repository's documented architecture +> and test layout. ## Overview @@ -38,7 +39,7 @@ export function getUserProfile(id: string) { - Use Conventional Commits. - Choose the prefix that describes the change; observed prefixes include - `build`, `chore`, `docs`, `fix`, and scoped variants such as + `build`, `chore`, `docs`, `feat`, `fix`, and scoped variants such as `fix(frontend)` and `fix(desktop)`. - Keep the subject concise and include a scope when it adds useful context. @@ -48,6 +49,7 @@ fix(desktop): honor PERISCOPE_VERSION override chore(git): sync attribution guard scripts docs: align layer-2 synthesis analysis tip SHA fix(frontend): remove stale ActivityMinimap and pass svelte-check +feat(parser): add session discovery for a new agent ``` ## Workflows @@ -99,6 +101,97 @@ workflow steps; trigger: "when doing update integration analysis doc". 2. Use a `docs:` Conventional Commit subject that names the alignment work. 3. Keep the analysis consistent with the current `merged` integration line. +### Add New Agent Integration + +**Trigger:** When adding support for a new AI agent parser/discovery path + +**Guide:** `/add-new-agent-integration` (instinct: +`periscope-workflow-add-new-agent-integration`) + +1. Implement a parser in `internal/parser/{agent}.go` with + `internal/parser/{agent}_test.go`. +2. Add discovery logic in `internal/parser/discovery.go`. +3. Update normalization in `internal/parser/types.go` and `taxonomy.go`. +4. Wire the agent into `internal/sync/engine.go` and integration tests. +5. Update agent directory/env configuration in `internal/config/config.go`. +6. Update frontend agent metadata in `frontend/src/lib/utils/agents.ts` and + related UI filters. +7. Update documentation (`README.md`, `AGENTS.md`) when user-facing behavior + changes. + +### Add New Feature (Full Stack) + +**Trigger:** When implementing a user-facing feature spanning backend and UI + +**Guide:** `/add-new-feature-full-stack` (instinct: +`periscope-workflow-add-new-feature-full-stack`) + +1. Design and implement DB schema changes in `internal/db/schema.sql` and + `internal/db/*.go`. +2. Add or update backend logic in `internal/server/` and `internal/sync/`. +3. Expose API endpoints in `internal/server/`. +4. Implement Svelte components/stores under `frontend/src/lib/`. +5. Update frontend types under `frontend/src/lib/api/types/`. +6. Add or update unit and e2e tests for the touched subsystems. +7. Update docs when operator or contributor behavior changes. + +### Backend Bugfix with Test + +**Trigger:** When fixing backend logic + +**Guide:** `/backend-bugfix-with-test` (instinct: +`periscope-instinct-backend-bugfix-with-test`) + +1. Fix the bug in the relevant Go package under `internal/`. +2. Add or update a regression test in the colocated `*_test.go` file. +3. Run targeted and affected package tests before handoff. + +### Frontend Bugfix with Test + +**Trigger:** When fixing frontend UI or store logic + +**Guide:** `/frontend-bugfix-with-test` (instinct: +`periscope-instinct-frontend-bugfix-with-test`) + +1. Fix the bug in the relevant Svelte/TypeScript module. +2. Add or update a Vitest or Playwright test as appropriate. +3. Run `cd frontend && npm test` and any affected e2e journeys. + +### Refactor and Test Split + +**Trigger:** When test files become large or mixed across concerns + +**Guide:** `/refactoring` (command scaffold: +`.claude/commands/refactoring.md`) + +1. Identify oversized or mixed test files. +2. Split into per-agent or per-feature test files. +3. Move or create fixtures under `internal/parser/testdata/` when needed. +4. Verify all tests still pass. + +### Database Schema Migration and Sync + +**Trigger:** When changing or extending the SQLite schema + +**Guide:** `/database-migration` (command scaffold: +`.claude/commands/database-migration.md`) + +1. Edit `internal/db/schema.sql` and related Go structs/queries. +2. Update sync logic in `internal/sync/` when ingestion behavior changes. +3. Add or update tests in `internal/db/*_test.go` and sync integration tests. +4. Handle resync/migration semantics without destroying archived session data. +5. Update frontend types when API payloads change. + +### Feature Development Scaffold + +**Trigger:** When starting a multi-file feature with unclear boundaries + +**Guide:** `/feature-development` (command scaffold: +`.claude/commands/feature-development.md`) + +Use the scaffold to sequence discovery, smallest coherent change, verification, +and handoff notes before expanding scope. + ### Testing **Trigger:** When verifying correctness @@ -119,6 +212,7 @@ workflow steps; trigger: "when doing update integration analysis doc". - PostgreSQL integration tests use the `pgtest` build tag and a dedicated test database. - Use `t.TempDir()` for isolated Go test data. +- Use `internal/parser/testdata/` for parser fixtures. ## Verified Commands @@ -130,3 +224,11 @@ workflow steps; trigger: "when doing update integration analysis doc". | `make e2e` | Run Playwright end-to-end tests | | `make vet` | Run Go static checks | | `make lint` | Run configured Go linters | + +## Workflow Command Scaffolds + +| Command | Scaffold path | +| --- | --- | +| `/database-migration` | `.claude/commands/database-migration.md` | +| `/feature-development` | `.claude/commands/feature-development.md` | +| `/refactoring` | `.claude/commands/refactoring.md` | diff --git a/.claude/commands/database-migration.md b/.claude/commands/database-migration.md new file mode 100644 index 000000000..153a914b3 --- /dev/null +++ b/.claude/commands/database-migration.md @@ -0,0 +1,35 @@ +--- +name: database-migration +description: Workflow command scaffold for database-migration in periscope. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /database-migration + +Use this workflow when working on **database-migration** in `periscope`. + +## Goal + +Database schema changes with migration files + +## Common Files + +- `**/schema.*` + +## 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 + +- Create migration file +- Update schema definitions +- Generate/update types + +## 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 diff --git a/.claude/commands/feature-development.md b/.claude/commands/feature-development.md new file mode 100644 index 000000000..668ba20d2 --- /dev/null +++ b/.claude/commands/feature-development.md @@ -0,0 +1,39 @@ +--- +name: feature-development +description: Workflow command scaffold for feature-development in periscope. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /feature-development + +Use this workflow when working on **feature-development** in `periscope`. + +## Goal + +Standard feature implementation workflow + +## Common Files + +- `frontend/src/lib/stores/*` +- `frontend/src/lib/api/*` +- `frontend/src/lib/api/types/*` +- `**/*.test.*` +- `**/api/**` + +## 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 feature implementation +- Add tests for feature +- Update documentation + +## 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 diff --git a/.claude/commands/refactoring.md b/.claude/commands/refactoring.md new file mode 100644 index 000000000..8a68fd72a --- /dev/null +++ b/.claude/commands/refactoring.md @@ -0,0 +1,35 @@ +--- +name: refactoring +description: Workflow command scaffold for refactoring in periscope. +allowed_tools: ["Bash", "Read", "Write", "Grep", "Glob"] +--- + +# /refactoring + +Use this workflow when working on **refactoring** in `periscope`. + +## Goal + +Code refactoring and cleanup workflow + +## Common Files + +- `src/**/*` + +## 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 + +- Ensure tests pass before refactor +- Refactor code structure +- Verify tests still pass + +## 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 diff --git a/.claude/ecc-tools.json b/.claude/ecc-tools.json index 01251f22b..027d8c260 100644 --- a/.claude/ecc-tools.json +++ b/.claude/ecc-tools.json @@ -2,11 +2,11 @@ "version": "1.3", "schemaVersion": "1.0", "generatedBy": "ecc-tools", - "generatedAt": "2026-07-28T00:55:21.186Z", + "generatedAt": "2026-07-28T14:38:14.771Z", "repo": "https://github.com/diazMelgarejo/periscope", "referenceSetReadiness": { - "score": 14, - "present": 1, + "score": 29, + "present": 2, "total": 7, "items": [ { @@ -40,8 +40,12 @@ { "id": "harness-compatibility", "label": "Harness compatibility", - "status": "missing", - "evidence": [], + "status": "present", + "evidence": [ + ".agents/skills/localization-paraglide/SKILL.md", + ".agents/skills/localization-paraglide/agents/openai.yaml", + ".agents/skills/localization-paraglide/references/paraglide-formatting.md" + ], "recommendation": "Add cross-harness, adapter-compliance, or harness-audit evidence for Claude, Codex, OpenCode, Zed, dmux, and agent surfaces." }, { @@ -49,6 +53,7 @@ "label": "Security evidence", "status": "present", "evidence": [ + "SECURITY.md", "scripts/git/audit_attribution.sh" ], "recommendation": "Attach security evidence such as SBOMs, SARIF, audit reports, or AgentShield evidence packs." @@ -63,63 +68,108 @@ ] }, "profiles": { - "requested": "core", - "recommended": "core", - "effective": "core", - "requestedAlias": "core", - "recommendedAlias": "core", - "effectiveAlias": "core" + "requested": "full", + "recommended": "full", + "effective": "developer", + "requestedAlias": "full", + "recommendedAlias": "full", + "effectiveAlias": "developer" }, - "requestedProfile": "core", - "profile": "core", - "recommendedProfile": "core", - "effectiveProfile": "core", + "requestedProfile": "full", + "profile": "developer", + "recommendedProfile": "full", + "effectiveProfile": "developer", "tier": "free", "requestedComponents": [ - "repo-baseline" + "repo-baseline", + "workflow-automation", + "security-audits", + "research-tooling", + "team-rollout", + "governance-controls" ], "selectedComponents": [ - "repo-baseline" + "repo-baseline", + "workflow-automation" ], "requestedAddComponents": [], "requestedRemoveComponents": [], "blockedRemovalComponents": [], - "tierFilteredComponents": [], + "tierFilteredComponents": [ + "security-audits", + "research-tooling", + "team-rollout", + "governance-controls" + ], "requestedRootPackages": [ - "runtime-core" + "runtime-core", + "workflow-pack", + "agentshield-pack", + "research-pack", + "team-config-sync", + "enterprise-controls" ], "selectedRootPackages": [ - "runtime-core" + "runtime-core", + "workflow-pack" ], "requestedPackages": [ - "runtime-core" + "runtime-core", + "workflow-pack", + "agentshield-pack", + "research-pack", + "team-config-sync", + "enterprise-controls" ], "requestedAddPackages": [], "requestedRemovePackages": [], "selectedPackages": [ - "runtime-core" + "runtime-core", + "workflow-pack" ], "packages": [ - "runtime-core" + "runtime-core", + "workflow-pack" ], "blockedRemovalPackages": [], - "tierFilteredRootPackages": [], - "tierFilteredPackages": [], + "tierFilteredRootPackages": [ + "agentshield-pack", + "research-pack", + "team-config-sync", + "enterprise-controls" + ], + "tierFilteredPackages": [ + "agentshield-pack", + "research-pack", + "team-config-sync", + "enterprise-controls" + ], "conflictingPackages": [], "dependencyGraph": { - "runtime-core": [] + "runtime-core": [], + "workflow-pack": [ + "runtime-core" + ] }, "resolutionOrder": [ - "runtime-core" + "runtime-core", + "workflow-pack" ], "requestedModules": [ - "runtime-core" + "runtime-core", + "workflow-pack", + "agentshield-pack", + "research-pack", + "team-config-sync", + "enterprise-controls" ], "selectedModules": [ - "runtime-core" + "runtime-core", + "workflow-pack" ], "modules": [ - "runtime-core" + "runtime-core", + "workflow-pack" ], "managedFiles": [ ".claude/skills/periscope/SKILL.md", @@ -131,7 +181,10 @@ ".codex/agents/explorer.toml", ".codex/agents/reviewer.toml", ".codex/agents/docs-researcher.toml", - ".claude/homunculus/instincts/inherited/periscope-instincts.yaml" + ".claude/homunculus/instincts/inherited/periscope-instincts.yaml", + ".claude/commands/database-migration.md", + ".claude/commands/feature-development.md", + ".claude/commands/refactoring.md" ], "packageFiles": { "runtime-core": [ @@ -145,6 +198,11 @@ ".codex/agents/reviewer.toml", ".codex/agents/docs-researcher.toml", ".claude/homunculus/instincts/inherited/periscope-instincts.yaml" + ], + "workflow-pack": [ + ".claude/commands/database-migration.md", + ".claude/commands/feature-development.md", + ".claude/commands/refactoring.md" ] }, "moduleFiles": { @@ -159,6 +217,11 @@ ".codex/agents/reviewer.toml", ".codex/agents/docs-researcher.toml", ".claude/homunculus/instincts/inherited/periscope-instincts.yaml" + ], + "workflow-pack": [ + ".claude/commands/database-migration.md", + ".claude/commands/feature-development.md", + ".claude/commands/refactoring.md" ] }, "files": [ @@ -211,14 +274,46 @@ "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/database-migration.md", + "description": "Workflow command scaffold for database-migration." + }, + { + "moduleId": "workflow-pack", + "path": ".claude/commands/feature-development.md", + "description": "Workflow command scaffold for feature-development." + }, + { + "moduleId": "workflow-pack", + "path": ".claude/commands/refactoring.md", + "description": "Workflow command scaffold for refactoring." + } + ], + "workflows": [ + { + "command": "database-migration", + "path": ".claude/commands/database-migration.md" + }, + { + "command": "feature-development", + "path": ".claude/commands/feature-development.md" + }, + { + "command": "refactoring", + "path": ".claude/commands/refactoring.md" } ], - "workflows": [], "adapters": { "claudeCode": { "skillPath": ".claude/skills/periscope/SKILL.md", "identityPath": ".claude/identity.json", - "commandPaths": [] + "commandPaths": [ + ".claude/commands/database-migration.md", + ".claude/commands/feature-development.md", + ".claude/commands/refactoring.md" + ] }, "codex": { "configPath": ".codex/config.toml", @@ -226,4 +321,4 @@ "skillPath": ".agents/skills/periscope/SKILL.md" } } -} \ No newline at end of file +} diff --git a/.claude/homunculus/instincts/inherited/periscope-instincts.yaml b/.claude/homunculus/instincts/inherited/periscope-instincts.yaml index 3601b987a..deb6e3461 100644 --- a/.claude/homunculus/instincts/inherited/periscope-instincts.yaml +++ b/.claude/homunculus/instincts/inherited/periscope-instincts.yaml @@ -1,17 +1,14 @@ # Instincts generated from https://github.com/diazMelgarejo/periscope -# Generated: 2026-07-28T00:55:34.446Z -# Harmonized with ECC run: 2026-07-28T01:26:19.263Z -# Additive replay from ECC run: 2026-07-28T13:55:47.517Z (PR #16 on merged) +# Generated: 2026-07-28T14:38:14.771Z +# Harmonized with ECC run: 2026-07-28T01:26:19.263Z (PR #16 on merged) +# Additive replay from ECC run: 2026-07-28T14:39:08.509Z (PR #18) # Version: 2.0 # Absorbed ID aliases from the second run: # - periscope-instinct-commit-format -> periscope-instinct-git-commit-format # - periscope-instinct-commit-length -> periscope-instinct-git-commit-length -# Additive instincts from PR #16 (no amputation of PR #10/#12 synthesis): -# - periscope-arch-type-based -# - periscope-workflow-update-integration-analysis-doc +# Synthesis: keep PR #16 harmonized instincts; union PR #18 workflow/testing instincts. # NOTE: This file supplements (does not replace) any existing curated instincts. # High-confidence manually curated instincts should be preserved alongside these. - --- id: periscope-commit-conventional trigger: "when writing a commit message" @@ -36,6 +33,7 @@ prefixes include: build, chore, fix. merged); chore(git): sync attribution guard scripts and cursor rules; fix(desktop): test PERISCOPE_VERSION override +--- --- id: periscope-commit-length trigger: "when writing a commit message" @@ -57,6 +55,7 @@ approximately 68 characters. - First ECC input: 59 characters across 1 commit - Second ECC input: 68 characters across 4 commits +--- --- id: periscope-naming-files trigger: "when creating a new file" @@ -77,6 +76,7 @@ Use kebab-case naming convention - Analyzed file naming patterns in repository - Dominant pattern: kebab-case +--- --- id: periscope-import-relative trigger: "when importing modules" @@ -97,6 +97,7 @@ Use relative imports for project files - Import analysis shows relative import pattern - Example: import { x } from '../lib/x' +--- --- id: periscope-export-style trigger: "when exporting from a module" @@ -117,6 +118,7 @@ Prefer named exports - Export pattern analysis - Dominant style: named +--- --- id: periscope-test-separate trigger: "when writing tests" @@ -140,6 +142,7 @@ which captures each subsystem's established layout. - Location guidance is intentionally centralized in `periscope-instinct-test-location` +--- --- id: periscope-workflow-dependency-update trigger: "when doing dependency update" @@ -176,6 +179,7 @@ Follow the dependency-update workflow: - Repository also contains Go and desktop manifests requiring their native dependency tooling +--- --- id: periscope-instinct-file-naming trigger: "When creating or renaming a file" @@ -197,6 +201,7 @@ kebab-case for frontend TypeScript files where established. - Pattern in codeStyle.namingConventions.files - The repository also contains Go and Rust code with language-specific naming +--- --- id: periscope-instinct-function-naming trigger: "When defining a function" @@ -217,6 +222,7 @@ those subsystems. - Pattern in codeStyle.namingConventions.functions +--- --- id: periscope-instinct-class-naming trigger: "When defining a class" @@ -236,6 +242,7 @@ Use PascalCase for TypeScript class names. - Pattern in codeStyle.namingConventions.classes +--- --- id: periscope-instinct-constant-naming trigger: "When defining a constant" @@ -256,6 +263,7 @@ established. - Pattern in codeStyle.namingConventions.constants +--- --- id: periscope-instinct-import-style trigger: "When importing modules" @@ -275,6 +283,7 @@ Prefer relative import paths for project-local frontend modules. - Pattern in codeStyle.importStyle +--- --- id: periscope-instinct-export-style trigger: "When exporting from a module" @@ -294,6 +303,7 @@ Prefer named exports where the surrounding frontend module follows that pattern. - Pattern in codeStyle.exportStyle +--- --- id: periscope-arch-type-based trigger: "when adding new code" @@ -317,6 +327,7 @@ Place code in the appropriate type folder for the affected subsystem, such as - Observed folders: `frontend/src/lib/components/`, `internal/`, `cmd/`, `desktop/src-tauri/src/` +--- --- id: periscope-instinct-git-commit-format trigger: "When writing a commit message" @@ -343,6 +354,7 @@ prefixes include `build`, `chore`, `docs`, `fix`, and scoped variants such as 'docs: integrative synthesis layer-2 on origin/merged', 'fix(frontend): remove stale ActivityMinimap and pass svelte-check' +--- --- id: periscope-instinct-git-commit-length trigger: "When writing a commit message" @@ -367,6 +379,7 @@ richer ECC sample). - Second ECC input: 68 characters across 4 commits - Layer-2 integration line: 55 characters across 6 commits +--- --- id: periscope-instinct-test-location trigger: "When adding or updating tests" @@ -388,6 +401,7 @@ unit tests with source, and keep Playwright journeys in `frontend/e2e/`. - Pattern in architecture.folderStructure.testLocation - Verified against repository `*_test.go`, `*.test.ts`, and `frontend/e2e/` +--- --- id: periscope-instinct-dependency-update trigger: "When updating dependencies for a package or language ecosystem" @@ -420,6 +434,7 @@ committing the dependency state together. - Commit example: 'build(deps): bump marked, svelte, postcss in frontend (onto merged)' +--- --- id: periscope-workflow-update-integration-analysis-doc trigger: "when doing update integration analysis doc" @@ -450,4 +465,701 @@ Follow the update-integration-analysis-doc workflow: - Workflow detected from layer-2 integration commit patterns - Observed file: `docs/INTEGRATION-SYNTHESIS-LAYER2-ANALYSIS.md` - Frequency: episodic during integrative merge and recovery work +--- +id: periscope-test-framework +trigger: "when writing tests" +confidence: 0.9 +domain: testing +source: repo-analysis +source_repo: https://github.com/diazMelgarejo/periscope +--- + +# Periscope Test Framework + +## Action + +Use jest as the test framework + +## Evidence + +- Test framework detected: jest +- File pattern: *.test.ts + +--- +--- +id: periscope-test-naming +trigger: "when creating a test file" +confidence: 0.85 +domain: testing +source: repo-analysis +source_repo: https://github.com/diazMelgarejo/periscope +--- + +# Periscope Test Naming + +## Action + +Name test files using the pattern: *.test.ts + +## Evidence + +- File pattern: *.test.ts +- Consistent across test files + +--- +--- +id: periscope-test-mocking +trigger: "when mocking dependencies in tests" +confidence: 0.75 +domain: testing +source: repo-analysis +source_repo: https://github.com/diazMelgarejo/periscope +--- + +# Periscope Test Mocking + +## Action + +Use vi.mock for mocking + +## Evidence + +- Mocking pattern detected: vi.mock +- Consistent across test files + +--- +--- +id: periscope-test-types +trigger: "when planning tests for a feature" +confidence: 0.7 +domain: testing +source: repo-analysis +source_repo: https://github.com/diazMelgarejo/periscope +--- + +# Periscope Test Types + +## Action + +Write unit, integration, e2e tests to match project standards + +## Evidence + +- Test types detected: unit, integration, e2e +- Coverage config: no + +--- +--- +id: periscope-workflow-database-migration +trigger: "when modifying the database schema or adding tables" +confidence: 0.7 +domain: workflow +source: repo-analysis +source_repo: https://github.com/diazMelgarejo/periscope +--- + +# Periscope Workflow Database Migration + +## Action + +Follow the database-migration workflow: +1. Create migration file +2. Update schema definitions +3. Generate/update types + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~4x per month +- Files: **/schema.* + +--- +--- +id: periscope-workflow-feature-development +trigger: "when implementing a new feature" +confidence: 0.9 +domain: workflow +source: repo-analysis +source_repo: https://github.com/diazMelgarejo/periscope +--- + +# Periscope Workflow Feature Development + +## Action + +Follow the feature-development workflow: +1. Add feature implementation +2. Add tests for feature +3. Update documentation + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~19x per month +- Files: frontend/src/lib/stores/*, frontend/src/lib/api/*, frontend/src/lib/api/types/* + +--- +--- +id: periscope-workflow-refactoring +trigger: "when refactoring code" +confidence: 0.6 +domain: workflow +source: repo-analysis +source_repo: https://github.com/diazMelgarejo/periscope +--- + +# Periscope Workflow Refactoring + +## Action + +Follow the refactoring workflow: +1. Ensure tests pass before refactor +2. Refactor code structure +3. Verify tests still pass + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~2x per month +- Files: src/**/* + +--- +--- +id: periscope-workflow-add-new-agent-integration +trigger: "when doing add new agent integration" +confidence: 0.6 +domain: workflow +source: repo-analysis +source_repo: https://github.com/diazMelgarejo/periscope +--- + +# Periscope Workflow Add New Agent Integration + +## Action + +Follow the add-new-agent-integration workflow: +1. Implement new parser in internal/parser/{agent}.go and test in internal/parser/{agent}_test.go +2. Add discovery logic for agent session files in internal/parser/discovery.go +3. Update internal/parser/types.go and taxonomy.go for agent/tool normalization +4. Wire agent into sync engine (internal/sync/engine.go, engine_integration_test.go) +5. Update config (internal/config/config.go) for agent directories/env vars +6. Update frontend agent color/metadata (frontend/src/lib/utils/agents.ts, agents.test.ts, app.css) +7. Update frontend session list and filters (frontend/src/lib/components/sidebar/SessionItem.svelte, SessionList.svelte, utils/agents.ts) +8. Update documentation (README.md, AGENTS.md, CLAUDE.md as needed) + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~2x per month +- Files: internal/parser/{agent}.go, internal/parser/{agent}_test.go, internal/parser/discovery.go + +--- +--- +id: periscope-workflow-add-new-feature-full-stack +trigger: "when doing add new feature full stack" +confidence: 0.65 +domain: workflow +source: repo-analysis +source_repo: https://github.com/diazMelgarejo/periscope +--- + +# Periscope Workflow Add New Feature Full Stack + +## Action + +Follow the add-new-feature-full-stack workflow: +1. Design and implement backend DB schema changes (internal/db/schema.sql, db.go, db_test.go) +2. Add/modify backend logic (internal/server/*.go, internal/sync/engine.go, parser changes as needed) +3. Expose new/updated API endpoints (internal/server/*.go) +4. Implement frontend Svelte components and stores (frontend/src/lib/components/{feature}/, stores/{feature}.svelte.ts) +5. Update frontend types (frontend/src/lib/api/types/*.ts) +6. Add/modify frontend tests (frontend/src/lib/stores/{feature}.test.ts, e2e tests if necessary) +7. Update documentation if needed + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~3x per month +- Files: internal/db/schema.sql, internal/db/db.go, internal/db/db_test.go + +--- +--- +id: periscope-workflow-dependency-bump-and-ci-update +trigger: "when doing dependency bump and ci update" +confidence: 0.7 +domain: workflow +source: repo-analysis +source_repo: https://github.com/diazMelgarejo/periscope +--- + +# Periscope Workflow Dependency Bump And Ci Update + +## Action + +Follow the dependency-bump-and-ci-update workflow: +1. Update package.json and package-lock.json for npm deps (frontend/package*.json) +2. Update .github/workflows/*.yml for CI tools +3. Update go.mod/go.sum for Go deps if needed +4. Adjust code/tests for breaking changes (e.g., test timing, type changes) +5. Verify all tests and builds pass + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~4x per month +- Files: frontend/package.json, frontend/package-lock.json, .github/workflows/*.yml + +--- +--- +id: periscope-workflow-backend-bugfix-with-test +trigger: "when doing backend bugfix with test" +confidence: 0.7 +domain: workflow +source: repo-analysis +source_repo: https://github.com/diazMelgarejo/periscope +--- + +# Periscope Workflow Backend Bugfix With Test + +## Action + +Follow the backend-bugfix-with-test workflow: +1. Identify and fix the bug in backend Go code (internal/server/, internal/parser/, internal/db/, internal/sync/) +2. Add or update a unit/integration test for the bug (internal/*_test.go) +3. Run all tests to verify fix + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~4x per month +- Files: internal/server/*.go, internal/parser/*.go, internal/db/*.go + +--- +--- +id: periscope-workflow-frontend-bugfix-with-test +trigger: "when doing frontend bugfix with test" +confidence: 0.65 +domain: workflow +source: repo-analysis +source_repo: https://github.com/diazMelgarejo/periscope +--- + +# Periscope Workflow Frontend Bugfix With Test + +## Action + +Follow the frontend-bugfix-with-test workflow: +1. Identify and fix the bug in Svelte/TS code (frontend/src/lib/components/, stores/) +2. Add or update a unit or E2E test (frontend/src/lib/stores/*.test.ts, frontend/e2e/*.ts) +3. Run all tests to verify fix + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~3x per month +- Files: frontend/src/lib/components/**/*.svelte, frontend/src/lib/stores/*.svelte.ts, frontend/src/lib/stores/*.test.ts + +--- +--- +id: periscope-workflow-refactor-and-test-split +trigger: "when doing refactor and test split" +confidence: 0.55 +domain: workflow +source: repo-analysis +source_repo: https://github.com/diazMelgarejo/periscope +--- + +# Periscope Workflow Refactor And Test Split + +## Action + +Follow the refactor-and-test-split workflow: +1. Identify large or mixed test files (e.g., parser_test.go) +2. Split into per-agent or per-feature test files (e.g., claude_parser_test.go, codex_parser_test.go) +3. Move or create testdata fixtures as needed +4. Update or add new tests in the new files +5. Verify all tests pass + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~1x per month +- Files: internal/parser/*_test.go, internal/parser/testdata/*, internal/server/*_test.go + +--- +--- +id: periscope-workflow-db-schema-migration-and-sync +trigger: "when doing db schema migration and sync" +confidence: 0.6 +domain: workflow +source: repo-analysis +source_repo: https://github.com/diazMelgarejo/periscope +--- + +# Periscope Workflow Db Schema Migration And Sync + +## Action + +Follow the db-schema-migration-and-sync workflow: +1. Edit internal/db/schema.sql to add/modify tables/columns +2. Update Go structs and queries in internal/db/*.go +3. Update sync logic in internal/sync/engine.go and related files +4. Add/modify tests to cover new schema (internal/db/db_test.go, engine_integration_test.go) +5. Handle migration/resync logic (ResyncAll, orphaned data copy, atomic DB swap) +6. Update frontend types if needed + +## Evidence + +- Workflow detected from commit patterns +- Frequency: ~2x per month +- Files: internal/db/schema.sql, internal/db/*.go, internal/sync/engine.go + +--- +--- +id: periscope-instinct-naming-files +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 Naming Files + +## Action + +Use snake_case for file names + +## Evidence + +- Pattern in codeStyle.namingConventions.files +- Consistent file naming in internal/parser/*_test.go + +--- +--- +id: periscope-instinct-naming-functions +trigger: "When defining a function" +confidence: 0.85 +domain: code-style +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Naming Functions + +## Action + +Use camelCase for function names + +## Evidence + +- Pattern in codeStyle.namingConventions.functions + +--- +--- +id: periscope-instinct-naming-classes +trigger: "When defining a class or struct" +confidence: 0.8 +domain: code-style +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Naming Classes + +## Action + +Use PascalCase for class/struct names + +## Evidence + +- Pattern in codeStyle.namingConventions.classes + +--- +--- +id: periscope-instinct-naming-constants +trigger: "When defining a constant" +confidence: 0.8 +domain: code-style +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Naming Constants + +## Action + +Use SCREAMING_SNAKE_CASE for constant names + +## Evidence + +- Pattern in codeStyle.namingConventions.constants + +--- +--- +id: periscope-instinct-test-file-pattern +trigger: "When creating a test file for TypeScript code" +confidence: 0.9 +domain: testing +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Test File Pattern + +## Action + +Name the file with the pattern *.test.ts + +## Evidence + +- Pattern in testing.filePattern +- frontend/src/lib/stores/sessions.test.ts + +--- +--- +id: periscope-instinct-test-framework +trigger: "When writing frontend tests" +confidence: 0.8 +domain: testing +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Test Framework + +## Action + +Use jest as the test framework + +## Evidence + +- Pattern in testing.framework + +--- +--- +id: periscope-instinct-test-mocking +trigger: "When mocking modules in frontend tests" +confidence: 0.8 +domain: testing +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Test Mocking + +## Action + +Use vi.mock for mocking + +## Evidence + +- Pattern in testing.mockingStyle + +--- +--- +id: periscope-instinct-test-types +trigger: "When writing tests for frontend TypeScript code" +confidence: 0.85 +domain: testing +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Test Types + +## Action + +Include unit, integration, and e2e tests as appropriate + +## Evidence + +- Pattern in testing.testTypes + +--- +--- +id: periscope-instinct-commit-format +trigger: "When writing a commit message" +confidence: 0.9 +domain: git +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Commit Format + +## Action + +Use a conventional commit prefix (feat, fix, build) followed by a colon and a short description + +## Evidence + +- Pattern in commits.prefixes +- Example: 'feat: add AI-powered Insights with multi-agent generation (#16)' + +--- +--- +id: periscope-instinct-commit-length +trigger: "When composing a commit message" +confidence: 0.7 +domain: git +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Commit Length + +## Action + +Keep the commit message around 60 characters on average + +## Evidence + +- Pattern in commits.averageLength + +--- +--- +id: periscope-instinct-add-new-agent-integration +trigger: "When adding support for a new agent type" +confidence: 0.95 +domain: workflow +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Add New Agent Integration + +## Action + +Implement parser, discovery, normalization, sync, config, frontend display, and documentation for the new agent + +## Evidence + +- Workflow: add-new-agent-integration +- Example commits and files for agent integration + +--- +--- +id: periscope-instinct-add-new-feature-full-stack +trigger: "When implementing a new user-facing feature spanning backend and frontend" +confidence: 0.92 +domain: workflow +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Add New Feature Full Stack + +## Action + +Update DB schema, backend logic, API, frontend components/stores, types, tests, and docs + +## Evidence + +- Workflow: add-new-feature-full-stack +- Example commits and files for full-stack features + +--- +--- +id: periscope-instinct-dependency-bump-and-ci-update +trigger: "When updating dependencies or CI configuration" +confidence: 0.99 +domain: workflow +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Dependency Bump And Ci Update + +## Action + +Update package.json, package-lock.json, .github/workflows, go.mod, go.sum, adjust code/tests for breaking changes, and verify all tests/builds pass + +## Evidence + +- Workflow: dependency-bump-and-ci-update +- Example commits and files for dependency updates + +--- +--- +id: periscope-instinct-backend-bugfix-with-test +trigger: "When fixing a backend bug" +confidence: 0.93 +domain: workflow +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Backend Bugfix With Test + +## Action + +Fix the bug in Go code and add or update a test to prevent regression + +## Evidence + +- Workflow: backend-bugfix-with-test +- Example commits and files for backend bugfixes + +--- +--- +id: periscope-instinct-frontend-bugfix-with-test +trigger: "When fixing a frontend bug" +confidence: 0.9 +domain: workflow +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Frontend Bugfix With Test + +## Action + +Fix the bug in Svelte/TS code and add or update a test to prevent regression + +## Evidence + +- Workflow: frontend-bugfix-with-test +- Example commits and files for frontend bugfixes + +--- +--- +id: periscope-instinct-refactor-and-test-split +trigger: "When test files become large or mixed" +confidence: 0.85 +domain: workflow +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Refactor And Test Split + +## Action + +Split tests into per-feature or per-agent files, update/move fixtures, and verify all tests pass + +## Evidence + +- Workflow: refactor-and-test-split +- Example commits and files for test refactoring + +--- +--- +id: periscope-instinct-db-schema-migration-and-sync +trigger: "When changing or extending the database schema" +confidence: 0.92 +domain: workflow +source: repo-analysis +source_repo: diazMelgarejo/periscope +--- + +# Periscope Instinct Db Schema Migration And Sync + +## Action + +Edit schema.sql, update Go structs/queries, sync logic, tests, migration/resync logic, and frontend types as needed + +## Evidence +- Workflow: db-schema-migration-and-sync +- Example commits and files for DB migrations diff --git a/.claude/identity.json b/.claude/identity.json index fa7972c3e..67d9140d3 100644 --- a/.claude/identity.json +++ b/.claude/identity.json @@ -7,8 +7,9 @@ "explanations": true }, "domains": [ + "go", "typescript" ], "suggestedBy": "ecc-tools-repo-analysis", - "createdAt": "2026-07-28T00:55:34.446Z" -} \ No newline at end of file + "createdAt": "2026-07-28T14:39:08.509Z" +} diff --git a/.claude/skills/periscope/SKILL.md b/.claude/skills/periscope/SKILL.md index ba8c5fa5d..83661ceb0 100644 --- a/.claude/skills/periscope/SKILL.md +++ b/.claude/skills/periscope/SKILL.md @@ -1,7 +1,8 @@ # periscope Development Patterns -> Synthesized from two ECC repository-analysis runs and verified against the -> repository's documented architecture and test layout. +> Synthesized from ECC repository-analysis runs (PR #16 harmonization + PR #18 +> additive replay) and verified against the repository's documented architecture +> and test layout. ## Overview @@ -38,7 +39,7 @@ export function getUserProfile(id: string) { - Use Conventional Commits. - Choose the prefix that describes the change; observed prefixes include - `build`, `chore`, `docs`, `fix`, and scoped variants such as + `build`, `chore`, `docs`, `feat`, `fix`, and scoped variants such as `fix(frontend)` and `fix(desktop)`. - Keep the subject concise and include a scope when it adds useful context. @@ -48,6 +49,7 @@ fix(desktop): honor PERISCOPE_VERSION override chore(git): sync attribution guard scripts docs: align layer-2 synthesis analysis tip SHA fix(frontend): remove stale ActivityMinimap and pass svelte-check +feat(parser): add session discovery for a new agent ``` ## Workflows @@ -99,6 +101,97 @@ workflow steps; trigger: "when doing update integration analysis doc". 2. Use a `docs:` Conventional Commit subject that names the alignment work. 3. Keep the analysis consistent with the current `merged` integration line. +### Add New Agent Integration + +**Trigger:** When adding support for a new AI agent parser/discovery path + +**Guide:** `/add-new-agent-integration` (instinct: +`periscope-workflow-add-new-agent-integration`) + +1. Implement a parser in `internal/parser/{agent}.go` with + `internal/parser/{agent}_test.go`. +2. Add discovery logic in `internal/parser/discovery.go`. +3. Update normalization in `internal/parser/types.go` and `taxonomy.go`. +4. Wire the agent into `internal/sync/engine.go` and integration tests. +5. Update agent directory/env configuration in `internal/config/config.go`. +6. Update frontend agent metadata in `frontend/src/lib/utils/agents.ts` and + related UI filters. +7. Update documentation (`README.md`, `AGENTS.md`) when user-facing behavior + changes. + +### Add New Feature (Full Stack) + +**Trigger:** When implementing a user-facing feature spanning backend and UI + +**Guide:** `/add-new-feature-full-stack` (instinct: +`periscope-workflow-add-new-feature-full-stack`) + +1. Design and implement DB schema changes in `internal/db/schema.sql` and + `internal/db/*.go`. +2. Add or update backend logic in `internal/server/` and `internal/sync/`. +3. Expose API endpoints in `internal/server/`. +4. Implement Svelte components/stores under `frontend/src/lib/`. +5. Update frontend types under `frontend/src/lib/api/types/`. +6. Add or update unit and e2e tests for the touched subsystems. +7. Update docs when operator or contributor behavior changes. + +### Backend Bugfix with Test + +**Trigger:** When fixing backend logic + +**Guide:** `/backend-bugfix-with-test` (instinct: +`periscope-instinct-backend-bugfix-with-test`) + +1. Fix the bug in the relevant Go package under `internal/`. +2. Add or update a regression test in the colocated `*_test.go` file. +3. Run targeted and affected package tests before handoff. + +### Frontend Bugfix with Test + +**Trigger:** When fixing frontend UI or store logic + +**Guide:** `/frontend-bugfix-with-test` (instinct: +`periscope-instinct-frontend-bugfix-with-test`) + +1. Fix the bug in the relevant Svelte/TypeScript module. +2. Add or update a Vitest or Playwright test as appropriate. +3. Run `cd frontend && npm test` and any affected e2e journeys. + +### Refactor and Test Split + +**Trigger:** When test files become large or mixed across concerns + +**Guide:** `/refactoring` (command scaffold: +`.claude/commands/refactoring.md`) + +1. Identify oversized or mixed test files. +2. Split into per-agent or per-feature test files. +3. Move or create fixtures under `internal/parser/testdata/` when needed. +4. Verify all tests still pass. + +### Database Schema Migration and Sync + +**Trigger:** When changing or extending the SQLite schema + +**Guide:** `/database-migration` (command scaffold: +`.claude/commands/database-migration.md`) + +1. Edit `internal/db/schema.sql` and related Go structs/queries. +2. Update sync logic in `internal/sync/` when ingestion behavior changes. +3. Add or update tests in `internal/db/*_test.go` and sync integration tests. +4. Handle resync/migration semantics without destroying archived session data. +5. Update frontend types when API payloads change. + +### Feature Development Scaffold + +**Trigger:** When starting a multi-file feature with unclear boundaries + +**Guide:** `/feature-development` (command scaffold: +`.claude/commands/feature-development.md`) + +Use the scaffold to sequence discovery, smallest coherent change, verification, +and handoff notes before expanding scope. + ### Testing **Trigger:** When verifying correctness @@ -119,6 +212,7 @@ workflow steps; trigger: "when doing update integration analysis doc". - PostgreSQL integration tests use the `pgtest` build tag and a dedicated test database. - Use `t.TempDir()` for isolated Go test data. +- Use `internal/parser/testdata/` for parser fixtures. ## Verified Commands @@ -130,3 +224,11 @@ workflow steps; trigger: "when doing update integration analysis doc". | `make e2e` | Run Playwright end-to-end tests | | `make vet` | Run Go static checks | | `make lint` | Run configured Go linters | + +## Workflow Command Scaffolds + +| Command | Scaffold path | +| --- | --- | +| `/database-migration` | `.claude/commands/database-migration.md` | +| `/feature-development` | `.claude/commands/feature-development.md` | +| `/refactoring` | `.claude/commands/refactoring.md` | diff --git a/.codex/AGENTS.md b/.codex/AGENTS.md index 072229cfc..8d3296e0c 100644 --- a/.codex/AGENTS.md +++ b/.codex/AGENTS.md @@ -21,6 +21,11 @@ The generated baseline enables GitHub, Context7, Exa, Memory, Playwright, and Se ## Workflow Files -- No dedicated workflow command files were generated for this repo. - -Use these workflow files as reusable task scaffolds when the detected repository workflows recur. \ No newline at end of file +- `.claude/commands/database-migration.md` +- `.claude/commands/feature-development.md` +- `.claude/commands/refactoring.md` + +Use these workflow files as reusable task scaffolds when the detected repository workflows recur. +Pair them with the synthesized instincts in +`.claude/homunculus/instincts/inherited/periscope-instincts.yaml` and the workflow +sections in the repo skill files above.