agent-knowledge-cli 0.1.2__py3-none-any.whl

agent_knowledge/assets/skills/memory-management/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: memory-management
+description: Read on session start. Manages adaptive durable memory across conversations. Use when reading or writing curated memory under agent-knowledge/Memory/.
+---
+
+# Memory Management
+
+Manages the adaptive project memory tree. Read this skill at session start.
+
+The memory directory path is provided by the session-start hook
+(e.g., `~/.cursor/projects/<project-id>/memory/MEMORY.md`).
+For project-shared memory, the canonical repo entrypoint is `./agent-knowledge`.
+Durable curated memory lives at `agent-knowledge/Memory/MEMORY.md`.
+
+---
+
+## Tree structure
+
+```text
+agent-knowledge/
+  Memory/
+    MEMORY.md               <- root memory note -- always loaded, keep it short
+    <topic>.md              <- flat branch note (no subtopics needed)
+    <topic>/
+      <topic>.md            <- branch entry note (same name as folder)
+      <subtopic>.md         <- leaf notes beside the entry
+    decisions/
+      decisions.md          <- decision log, newest first
+      YYYY-MM-DD-slug.md
+  Evidence/
+    raw/
+    imports/
+  Sessions/                 <- milestone-oriented temporary state
+  Outputs/
+  Dashboards/
+  STATUS.md
+```
+
+### Branch convention
+
+- **One branch = one functional domain**. Do not lump unrelated subsystems together.
+- **Folder name = ontology node**. The folder is the topic.
+- **Same-name entry note** (`<topic>/<topic>.md`) = summary and routing for the branch.
+- **Flat note** (`<topic>.md`) when there are no subtopics yet.
+- **Promote to folder** only when the topic grows subtopics.
+- **Keep each note under ~150 lines**. Split if bigger.
+- **Link related notes** to each other with relative markdown links.
+- **Use the project's own terminology** for branch names, not generic templates.
+- **Do not use generic names** like "architecture" or "conventions" to group unrelated content.
+  Instead, use the project's own domain names (e.g., perception, navigation, localization).
+
+Evidence (`agent-knowledge/Evidence/raw/` and `agent-knowledge/Evidence/imports/`) is separate from curated memory (`agent-knowledge/Memory/`).
+Never copy raw evidence into memory. Distill only stable, verified facts.
+Generated structural outputs belong in `Evidence/` or `Outputs/` first.
+Only curated notes under `Memory/` are durable project knowledge.
+
+---
+
+## Durable note requirements
+
+Every durable memory note must have YAML frontmatter.
+
+Branch notes use these sections:
+
+| Section | Content | Updated when |
+|---------|---------|--------------|
+| **Purpose** | One sentence: what this area covers | At creation; rarely changes |
+| **Current State** | Verified facts about what is true now | Every writeback |
+| **Recent Changes** | Rolling log, YYYY-MM-DD format, pruned after ~4 weeks | After meaningful changes |
+| **Decisions** | Links to `decisions/YYYY-MM-DD-slug.md` | When a decision is recorded |
+| **Open Questions** | Unresolved items for future sessions | When identified; removed when resolved |
+
+Use markdown links for portability. Avoid wiki-links and tool-specific metadata.
+
+---
+
+## Reading the tree
+
+1. `Memory/MEMORY.md` loads automatically first.
+2. Identify which branch notes the task touches from the Branches section.
+3. Read only the relevant branch entry notes -- keep context lean.
+4. For branches with folders, read subtopic notes only if the specific detail is needed.
+5. Do not read branches unrelated to your task.
+
+---
+
+## Writing to the tree
+
+- **Memory/MEMORY.md**: short branch summaries + links. No dense detail.
+- **Branch entry note**: all durable facts for that area, organized by section.
+- **Subtopic note**: created only when an entry note grows beyond ~150 lines.
+- **Decision file**: one file per architectural decision, linked from the branch.
+
+Format for facts: lead with the fact. For lessons: add **Why:** and **How to apply:**.
+
+---
+
+## Bootstrap
+
+If `agent-knowledge/Memory/MEMORY.md` is missing or empty:
+-> Read and follow the `project-ontology-bootstrap` skill before any other work.
+
+---
+
+## When to write back
+
+Write to memory when any of these happen:
+- A new architectural decision is made
+- A pattern or convention is confirmed
+- A gotcha is discovered
+- A feature area is substantially completed or changed
+- A recurring mistake is corrected
+
+Do NOT write:
+- In-progress task state -> session file only
+- Speculative plans -> wait until confirmed
+- Facts already in git history that are easily re-discoverable
+- Raw evidence -> keep it in `Evidence/`
+- Machine-generated summaries -> keep in `Evidence/` or `Outputs/` until curated
+
+---
+
+## Compaction
+
+When `Memory/MEMORY.md` grows noisy or a branch note exceeds ~150 lines:
+-> Read and follow the `memory-compaction` skill.
+
+---
+
+## Explicit user requests
+
+- "Remember X" -> save it immediately to the relevant branch note
+- "Forget X" -> remove or mark stale in the relevant branch note
+- "Why did we choose X" -> read `decisions/decisions.md` and the linked decision file

agent_knowledge/assets/skills/project-ontology-bootstrap/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: project-ontology-bootstrap
+description: Bootstrap an adaptive project knowledge tree. Use when agent-knowledge/Memory/MEMORY.md is missing, broken, or too generic.
+---
+
+# Project Ontology Bootstrap
+
+Creates a minimal knowledge scaffold, then the agent infers the ontology from the
+real project. Run this once -- then maintain with the writeback rule.
+
+## When to use
+
+- `agent-knowledge/Memory/MEMORY.md` does not exist or is empty
+- `Memory/MEMORY.md` exists but is still generic bootstrap content
+- User says "initialize memory", "bootstrap memory", or "set up project memory"
+- Starting work on an inherited repo with no prior agent memory
+
+---
+
+## Step 0 -- Verify the local pointer
+
+The project entrypoint is `./agent-knowledge`.
+
+- `./agent-knowledge` must be a symlink or junction to the real dedicated knowledge folder
+- The external folder is the source of truth
+- Manual and scripted bootstrap still write through `./agent-knowledge` as the local handle
+
+If the pointer does not exist yet, create it first with:
+
+```bash
+scripts/install-project-links.sh --slug <project-slug> --repo /path/to/project
+```
+
+---
+
+## Step 1 -- Run the bootstrap script
+
+```bash
+scripts/bootstrap-memory-tree.sh /path/to/project
+```
+
+This creates a minimal scaffold:
+```text
+agent-knowledge/
+  Memory/
+    MEMORY.md           <- root durable memory note
+    decisions/
+      decisions.md      <- decision log (same-name convention)
+  Evidence/
+    raw/
+    imports/
+  Sessions/
+  Outputs/
+  Dashboards/
+  Templates/
+  .obsidian/
+  STATUS.md
+```
+
+The script detects a profile hint (web-app, robotics, ml-platform, or hybrid) and
+stores it in STATUS.md. The hint does NOT create branch notes -- that is the agent's job.
+
+---
+
+## Step 2 -- Inspect the repo and infer the ontology
+
+After the scaffold exists, inspect:
+- Manifests and lockfiles
+- Directory structure
+- Docs (README.md, AGENTS.md, CLAUDE.md, docs/)
+- Config files
+- Test directories
+- Workflow files
+- Any evidence already present under Evidence/
+
+From these signals, determine the project's natural decomposition. Use the project's
+own terminology, not generic template names.
+
+---
+
+## Step 3 -- Create initial branch notes
+
+Create one branch per functional domain in the project. Use the same-name convention:
+
+- Small topic with no subtopics: `Memory/<topic>.md`
+- Bigger topic with subtopics: `Memory/<topic>/<topic>.md`
+
+Each branch note must stay under ~150 lines. If a topic is too big for one note,
+split it into a folder with subtopic notes.
+
+Do NOT put the whole system description in a single file. Split by functional domain.
+
+Example for a robotics project:
+```text
+Memory/
+  MEMORY.md
+  stack.md                        # build system, deps, hardware platform
+  perception/
+    perception.md                 # vision pipeline overview
+    object-detection.md           # YOLO, TensorRT, tracking
+    lane-detection.md             # lane following
+  navigation/
+    navigation.md                 # path planning, row driving
+    path-following.md             # pure pursuit, drive controller
+  localization/
+    localization.md               # EKF, IMU, GNSS, LiDAR odometry
+  cloud-interface.md              # STOMP, fleet management
+  vehicle-interface.md            # CAN, LLC, hardware abstraction
+  safety.md                       # obstacle detection, fault monitoring
+  decisions/
+    decisions.md
+```
+
+Rules:
+- Use the project's own decomposition and terminology, not generic templates
+- Each branch = one focused functional domain. Do NOT use generic names like
+  "architecture" or "conventions" to lump unrelated subsystems together.
+- Keep each note under ~150 lines. Split if bigger.
+- Link related notes to each other with relative markdown links
+  (e.g., `See [localization](localization/localization.md) for sensor fusion`)
+- Do not create empty placeholder branches
+- Each branch entry note should have frontmatter, Purpose, Current State, Recent Changes,
+  Decisions, and Open Questions sections
+
+---
+
+## Step 4 -- Seed from immediately available facts
+
+For each branch you create, seed it with verified facts:
+
+- Read manifests, configs, docs, and directory structure
+- Write only confirmed facts to Current State
+- Do not invent facts or speculate
+- If a source is machine-generated, verify against the repo before writing to Memory/
+
+---
+
+## Step 5 -- Update Memory/MEMORY.md
+
+Add links to each branch note in the Branches section:
+
+```markdown
+## Branches
+
+- [Stack](stack.md) -- Python 3.10, ROS2 Humble, colcon build system
+- [Perception](perception/perception.md) -- Camera pipeline, YOLO detection, depth fusion
+- [Navigation](navigation/navigation.md) -- Nav2 stack, custom costmap layers
+```
+
+---
+
+## Step 6 -- Trigger history backfill
+
+Bootstrap creates structure only. To fill it with real project history:
+
+```bash
+scripts/import-agent-history.sh /path/to/project
+```
+
+Then follow the `history-backfill` skill to distill evidence into memory.
+
+---
+
+## Output checklist
+
+After bootstrap, verify:
+- [ ] `agent-knowledge/Memory/MEMORY.md` exists and uses YAML frontmatter
+- [ ] `agent-knowledge/Memory/decisions/decisions.md` exists
+- [ ] Each branch note has a Purpose and at least one entry in Current State
+- [ ] `agent-knowledge/Evidence/raw/` and `agent-knowledge/Evidence/imports/` exist
+- [ ] `agent-knowledge/Sessions/` exists
+- [ ] `Memory/MEMORY.md` is still short enough to scan quickly
+- [ ] No INDEX.md files were created

agent_knowledge/assets/skills/session-management/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: session-management
+description: Read on session start. Tracks work progress in session files during conversations. Use when recording milestones, decisions, blockers, or when the session-start hook creates a session file.
+---
+
+# Session Management
+
+Session files preserve in-progress context through long sessions and help new sessions
+resume quickly from prior work.
+
+The session file path is provided by the session-start hook
+(e.g., `~/.cursor/projects/<project-id>/sessions/`).
+For project-shared session notes, use `agent-knowledge/Sessions/`.
+
+---
+
+## Session vs memory — the key distinction
+
+| Session file | Memory tree |
+|-------------|------------|
+| Ephemeral — deleted or archived when no longer active | Durable — persists across all sessions |
+| Tracks current task progress | Tracks stable project understanding |
+| Milestone-oriented log entries | Fact-oriented structured files |
+| Private to one conversation thread | Shared across all agents and conversations |
+| Write freely, prune aggressively | Write carefully, never speculate |
+
+**Rule**: if a fact belongs to future sessions, it goes in memory. If it only matters for this session, it stays in the session file.
+
+---
+
+## Session file format
+
+Filename: `YYYY-MM-DD-<title-slug>-<UUID>.tmp`
+(slug defaults to `session` until the task is clear, then updated)
+
+```markdown
+## Current State
+[One-line description of current focus]
+
+### Completed
+- [Milestone outcomes, not step-by-step details]
+
+### In Progress
+- [What is actively being worked on]
+
+### Blockers
+- [What is preventing progress]
+
+### Notes for Next Session
+- [What to load immediately when resuming]
+
+### Context to Load
+- [Which memory areas and files to read on resume]
+
+## Session Log
+**HH:MM** - [Milestone outcome in one line]
+```
+
+---
+
+## How to update
+
+1. Read the current session file first.
+2. If nothing meaningful happened since the last log entry, do not write.
+3. If a meaningful milestone occurred, write one checkpoint:
+   - Refresh **Current State**
+   - Update Completed / In Progress / Blockers
+   - Add one timestamped Session Log line
+4. Set the session title once the task is clear.
+5. Keep entries milestone-oriented — not every tool call.
+
+---
+
+## When NOT to write
+
+- Between sequential tool calls in the same task
+- For trivial progress (e.g., reading a file, minor edits)
+- When the hook fires but no real milestone occurred
+
+---
+
+## Writeback gate — before closing a session
+
+Before ending a session with meaningful output, check:
+
+**Did this session change durable project understanding?**
+
+If yes — follow the `memory-writeback` rule:
+1. Identify the durable fact (decision, pattern, gotcha, lesson)
+2. Write it to the relevant `agent-knowledge/Memory/<area>.md`
+3. For architectural decisions: use the `decision-recording` skill
+4. Once written to memory, remove or summarize it in the session file (avoid duplication)
+
+If no meaningful new project understanding was produced — no writeback needed. State this explicitly:
+> Memory writeback: none needed (no new durable facts this session).
+
+Examples that should NOT trigger writeback:
+- Progress within one task but no stable new conclusion
+- Temporary debugging state
+- Notes that only matter to the current conversation
+- Evidence review that did not change curated understanding
+
+---
+
+## Session log entry format
+
+```markdown
+**HH:MM** - [Milestone outcome in one line]
+```
+
+Example:
+```markdown
+**14:32** - bootstrapped memory tree (hybrid profile, 5 area files created)
+**15:10** - backfill complete: stack, architecture, gotchas populated from git history
+**15:45** - decision recorded: use-raw-sql (decisions/2025-01-15-use-raw-sql.md)
+```

agent_knowledge/assets/skills-cursor/create-rule/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: create-rule
+description: >-
+  Create Cursor rules for persistent AI guidance. Use when you want to create a
+  rule, add coding standards, set up project conventions, configure
+  file-specific patterns, create RULE.md files, or asks about .cursor/rules/ or
+  AGENTS.md.
+---
+# Creating Cursor Rules
+
+Create project rules in `.cursor/rules/` to provide persistent context for the AI agent.
+
+## Gather Requirements
+
+Before creating a rule, determine:
+
+1. **Purpose**: What should this rule enforce or teach?
+2. **Scope**: Should it always apply, or only for specific files?
+3. **File patterns**: If file-specific, which glob patterns?
+
+### Inferring from Context
+
+If you have previous conversation context, infer rules from what was discussed. You can create multiple rules if the conversation covers distinct topics or patterns. Don't ask redundant questions if the context already provides the answers.
+
+### Required Questions
+
+If the user hasn't specified scope, ask:
+- "Should this rule always apply, or only when working with specific files?"
+
+If they mentioned specific files and haven't provided concrete patterns, ask:
+- "Which file patterns should this rule apply to?" (e.g., `**/*.ts`, `backend/**/*.py`)
+
+It's very important that we get clarity on the file patterns.
+
+Use the AskQuestion tool when available to gather this efficiently.
+
+---
+
+## Rule File Format
+
+Rules are `.mdc` files in `.cursor/rules/` with YAML frontmatter:
+
+```
+.cursor/rules/
+  typescript-standards.mdc
+  react-patterns.mdc
+  api-conventions.mdc
+```
+
+### File Structure
+
+```markdown
+---
+description: Brief description of what this rule does
+globs: **/*.ts  # File pattern for file-specific rules
+alwaysApply: false  # Set to true if rule should always apply
+---
+
+# Rule Title
+
+Your rule content here...
+```
+
+### Frontmatter Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `description` | string | What the rule does (shown in rule picker) |
+| `globs` | string | File pattern - rule applies when matching files are open |
+| `alwaysApply` | boolean | If true, applies to every session |
+
+---
+
+## Rule Configurations
+
+### Always Apply
+
+For universal standards that should apply to every conversation:
+
+```yaml
+---
+description: Core coding standards for the project
+alwaysApply: true
+---
+```
+
+### Apply to Specific Files
+
+For rules that apply when working with certain file types:
+
+```yaml
+---
+description: TypeScript conventions for this project
+globs: **/*.ts
+alwaysApply: false
+---
+```
+
+---
+
+## Best Practices
+
+### Keep Rules Concise
+
+- **Under 50 lines**: Rules should be concise and to the point
+- **One concern per rule**: Split large rules into focused pieces
+- **Actionable**: Write like clear internal docs
+- **Concrete examples**: Ideally provide concrete examples of how to fix issues
+
+---
+
+## Example Rules
+
+### TypeScript Standards
+
+```markdown
+---
+description: TypeScript coding standards
+globs: **/*.ts
+alwaysApply: false
+---
+
+# Error Handling
+
+\`\`\`typescript
+// ❌ BAD
+try {
+  await fetchData();
+} catch (e) {}
+
+// ✅ GOOD
+try {
+  await fetchData();
+} catch (e) {
+  logger.error('Failed to fetch', { error: e });
+  throw new DataFetchError('Unable to retrieve data', { cause: e });
+}
+\`\`\`
+```
+
+### React Patterns
+
+```markdown
+---
+description: React component patterns
+globs: **/*.tsx
+alwaysApply: false
+---
+
+# React Patterns
+
+- Use functional components
+- Extract custom hooks for reusable logic
+- Colocate styles with components
+```
+
+---
+
+## Checklist
+
+- [ ] File is `.mdc` format in `.cursor/rules/`
+- [ ] Frontmatter configured correctly
+- [ ] Content under 500 lines
+- [ ] Includes concrete examples