Merge pull request #15 from diazMelgarejo/merged-local-rebased-on-origin

Author: diazMelgarejo

.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,13 +39,17 @@ export function getUserProfile(id: string) {
 
 - Use Conventional Commits.
 - Choose the prefix that describes the change; observed prefixes include
-  `build`, `chore`, and `fix`.
+  `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.
 
 ```text
 build(deps): update frontend dependencies
 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
@@ -82,6 +87,111 @@ chore(git): sync attribution guard scripts
 4. Run the checks for each affected subsystem.
 5. Commit the manifest and lockfile together with a `build(deps)` subject.
 
+### Integration Analysis Doc
+
+**Trigger:** When updating layer-2 integrative synthesis verification or tip SHA
+
+**Guide:** `/update-integration-analysis`
+
+**Instinct:** `periscope-workflow-update-integration-analysis-doc` — numbered
+workflow steps; trigger: "when doing update integration analysis doc".
+
+1. Edit `docs/INTEGRATION-SYNTHESIS-LAYER2-ANALYSIS.md` for verification gates,
+   branch references, or tip SHA alignment.
+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
@@ -102,6 +212,7 @@ chore(git): sync attribution guard scripts
 - 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
 
@@ -113,3 +224,11 @@ chore(git): sync attribution guard scripts
 | `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` |

.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.

.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.

.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.