Add .kiro/steering/ as persistent project memory for CC-SDD / Kiro
workflows. Three core files (product, tech, structure) capture
purpose, stack, and organization patterns; three custom files
(database, api-standards, error-handling) pin the load-bearing
project-specific conventions:
- group_id isolation and the Graphiti adapter / event-loop singleton
- {success, data|error} envelope and the Task polling contract
- reasoning-model output stripping and the retry_with_backoff helper
Files focus on patterns and decisions, not catalogs, per the
steering-principles "golden rule".
Adopt CC-SDD (Kiro) as the project's spec-driven planning tool, with
plans persisted in .kiro/specs/ and a checkpoint after every task
(strictest cadence — no code without an approved plan).
CC-SDD install (via npx cc-sdd@latest --claude --lang en):
- .kiro/settings/rules/: EARS format, gap-analysis, design and
requirements review gates, design discovery, tasks generation,
steering principles, parallel-task analysis.
- .kiro/settings/templates/: specs (init, requirements, design, tasks,
research) and steering (product/tech/structure plus optional
api-standards/auth/db/deployment/error-handling/security/testing).
- .claude/commands/kiro/: 11 Kiro slash commands — spec-init,
spec-requirements, spec-design, spec-tasks, spec-impl, spec-status,
steering, steering-custom, validate-gap, validate-design,
validate-impl.
Local additions:
- .claude/commands/plan.md: /plan [task] wrapper that picks up the task
from $ARGUMENTS or a single .ticket/<n>.md snapshot, walks the Kiro
flow (steering -> spec-init -> spec-requirements -> validate-gap ->
spec-design -> validate-design -> spec-tasks) and stops for human
approval after each artefact. Refuses "just code it" requests.
- .claude/hooks/session_start.sh: extend to print active tickets
(.ticket/*.md) and open specs (.kiro/specs/*/) with phase from
spec.json, alongside the existing branch/state line.
Documentation: .claude/onboarding/step4_workflow/01_tool_decision.md
Adapt the Notion onboarding prompt — originally Jira/MCP-oriented — to
this project's actual issue tracker (GitHub at
salestech-group/MiroFish) using the gh CLI.
Slash commands (.claude/commands/):
- /ticket <number>: fetch a GitHub issue via gh, self-assign, try to
add an in-progress label (skips silently if the label doesn't exist),
and snapshot the issue (frontmatter + body) to .ticket/<n>.md so
later planning steps can read the description without refetching.
- /ticket-list: interactive overview of issues; asks for filters
(open/closed, status, assignee, milestone, labels) and runs a single
gh issue list with the answers, rendering a compact markdown table.
Workspace:
- .ticket/repo.md declares the target repo (GitHub equivalent of the
Jira "board.md" referenced in the prompt).
- .gitignore: ignore .ticket/* except repo.md and .gitkeep so cached
ticket markdowns stay local.
Settings:
- Allow-list gh issue view/list/edit/comment, gh repo view,
gh pr view/list, gh auth status to avoid permission prompts.
Documentation: .claude/onboarding/step3_planning/01_ticket_sync.md
Permissions:
- Allow npm run/test/install, uv run/sync, docker (compose), and the
common read-only/staging git commands so routine work doesn't trigger
permission prompts.
- Deny Read/Write/Edit on uploads/ and .codegraph/ (auto-generated and
user-data paths) in addition to the existing .env*/secrets/ blocks.
Hooks:
- SessionStart: print branch, ahead/behind vs upstream, and working-tree
state at session start so context is visible immediately.
- PreToolUse (Read|Write|Edit|Bash|NotebookEdit): defence-in-depth
guard that intercepts attempts to access .env / secrets/ paths (and
bash commands targeting them) with a friendly, logged refusal on top
of the permissions.deny rules.
PostToolUse formatter is intentionally skipped — the project has no
configured formatter (per the Step 1 conventions decision).
The Stop hook (quality gate) will be configured in Step 6.
Documentation: .claude/onboarding/step2_setup/01_settings_analysis.md
Bring repo docs in line with the Graphiti+Neo4j migration and prepare
the codebase for Spec-Driven Development.
CLAUDE.md:
- Promote Neo4j + Graphiti to primary memory/graph layer; mark Zep
Cloud as deprecated / compat-only.
- Document the full env-var surface: NEO4J_*, EMBEDDING_MODEL, optional
LLM_BOOST_* block.
- Codify must-respect implementation rules (Task model for long ops,
reasoning-output stripping, simulation IPC, subprocess cleanup,
startup recovery, per-project group_id isolation, chat prefix
injection).
- Note i18n (vue-i18n + /locales/) and Docker prerequisite for dev.
README.md / README-EN.md / README-ZH.md:
- Resolve unresolved merge-conflict markers in README.md left over from
the feat/graphiti-neo4j-migration merge (file was broken Markdown).
- Lead with Docker as the recommended deployment path; keep source
install as a documented alternative.
- Replace Zep env vars with NEO4J_URI / NEO4J_USER / NEO4J_PASSWORD /
EMBEDDING_MODEL across all three READMEs.
- Add optional LLM_BOOST_* block with omit-if-unused note.
- Fix language-switcher links between the three READMEs.
.claude/onboarding/step1_codebase/:
- Document repo analysis, CLAUDE.md conventions decisions, and README
resolution choices.
- Add sans-serif font for English left-pane (status, workflow sections)
- Shorten English workflow step descriptions
- Reduce English report title font-size from 36px to 28px
- Use sans-serif font for English titles, descriptions and navbar
- Shorten English hero text to avoid overflow
- Fix :global() scoped CSS issue that was setting root font-size to 3.5rem
- Use separate unscoped style block for html[lang] selectors
Background threads (graph building, simulation prep, report generation,
profile generation) now inherit the requesting user's locale preference.
Previously these fell back to 'zh' because Flask request context was
unavailable in spawned threads.
Ensure poster_type stays PascalCase English and stance stays English enum
values regardless of language setting. Only natural language fields follow
the user's language preference.
The language instruction was causing LLM to change entity/relation naming
conventions. Now explicitly enforce PascalCase/UPPER_SNAKE_CASE for technical
identifiers while only applying language preference to description fields.
- Changed error messages to reflect the new configuration requirement for Neo4j.
- Ensured consistent handling of missing credentials across multiple functions.
- Replace ZEP_API_KEY with NEO4J_URI/USER/PASSWORD in env var section
- Add Neo4j as a prerequisite with install instructions for macOS/Linux/Windows
- Add EMBEDDING_MODEL note for Gemini API users
- Add migration note: no third-party account needed, free and no rate limits
- Update both Chinese (README.md) and English (README-EN.md) docs
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Replaces the paid, rate-limited Zep Cloud service with Graphiti (graphiti-core
0.11.6) backed by a local Neo4j instance — free, unlimited, and self-hosted.
Key changes:
- Add GraphitiAdapter: drop-in Zep-compatible wrapper around Graphiti with a
persistent event-loop thread to avoid asyncio/Neo4j driver conflicts
- Switch LLM client to native GeminiClient + GeminiEmbedder (text-embedding-004
fails on Gemini compat endpoint; use google-genai SDK directly)
- Add _GeminiReranker passthrough replacing OpenAIRerankerClient (which
hardcodes gpt-4.1-nano and uses logprobs unsupported by Gemini)
- Fix Cypher queries: use s.uuid/t.uuid for edge source/target instead of
r.source_node_uuid (null property in Graphiti's schema)
- Add ontology-based entity type classifier (_classify_entity_type) so nodes
get colored by type in the D3 graph visualization instead of all being Entity
- Apply classifier in ZepEntityReader so filter_defined_entities finds entities
(previously 0 personas loaded because all labels were ['Entity'])
- Add startup recovery: auto-mark graph_building projects as graph_completed
on backend restart if Neo4j already has their data
- Add resume capability to graph build: skip already-processed episodes after
a restart (断点续传)
- Add non-blocking graph data cache with background refresh in graph.py
- Add EMBEDDING_MODEL config (default: gemini-embedding-001 for Gemini users)
- Add CLAUDE.md with project architecture and dev commands
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Dominik Seemann
stg
666ghj
ghostubborn
Abhishek Yadav