evizi-kit 1.0.0

package/kits/shared/skills/workspace-ai-nav-creator/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: workspace-ai-nav-creator
+description: Generate a comprehensive workspace AI navigation file — either AGENTS.md (GitHub Copilot / Cursor) or CLAUDE.md (Claude Code) — for any multi-repository workspace. Scans the workspace to discover repositories, AI configuration (agents, skills, CLAUDE.md), tech stacks, and project structure, then produces a structured output file that guides AI navigation, context switching, and documentation references. Use when asked to create an AGENTS.md, create a CLAUDE.md, generate workspace documentation for AI, scaffold multi-repo AI navigation, or set up AI workspace rules. Triggers on requests like "create AGENTS.md", "create CLAUDE.md", "generate AGENTS.md for this workspace", "set up AI workspace navigation", "scaffold CLAUDE.md".
+---
+
+# Workspace AI Navigation File Creator
+
+Scan a workspace and generate a persistent instruction file (`AGENTS.md` for GitHub Copilot / Cursor, or `CLAUDE.md` for Claude Code) that guides the AI to:
+- Navigate to the **correct repository** for any given task
+- Invoke the **correct agents** for each workflow step
+- Follow workspace-specific commands, conventions, and documentation rules
+
+## Workflow
+
+### Step 1: Discover Workspace Structure
+
+Scan the workspace root to identify:
+
+1. **Repositories** — directories containing `.git/` folders
+2. **AI configuration** — check for:
+   - `.github/agents/` (GitHub Copilot agents)
+   - `.github/skills/` (shared skills)
+   - `.cursor/agents/` (Cursor agents)
+   - `.cursor/skills/` (shared skills)
+   - `.claude/agents/` (Claude Code subagents)
+   - `.claude/skills/` (Claude Code skills)
+   - `CLAUDE.md` (Claude Code project instructions)
+   - `AGENTS.md` (existing file to update)
+3. **Project config** — `.documents-design/project.config.json`
+4. **Specification docs** — `.documents-design/` folder containing ticket and feature documentation
+5. **Package managers** — `package.json`, `pom.xml`, `build.gradle`, `Cargo.toml`, `go.mod`, `requirements.txt`, `Gemfile`, `*.csproj`, etc.
+
+For each discovered repository, extract:
+- **Name** — directory name
+- **Purpose** — infer from directory contents (src code, tests, infra, docs, etc.)
+- **Tech stack** — infer from config files, dependencies, and source files
+- **Key directories** — `src/`, `config/`, `tests/`, etc.
+- **Package manager** — npm/yarn/pnpm, maven, gradle, cargo, go, pip, etc.
+- **Build/run commands** — from `package.json` scripts, `Makefile`, etc.
+
+### Step 2: Detect AI Configuration
+
+For each AI configuration system found in Step 1, catalog:
+
+**GitHub Copilot agents** (`.github/agents/`):
+- List each agent file name and its `description` frontmatter
+
+**Cursor agents** (`.cursor/agents/`):
+- List each agent file name and its `description` frontmatter
+
+**Claude Code subagents** (`.claude/agents/`):
+- List each subagent file name and its `description` frontmatter
+
+**Skills** (`.github/skills/`, `.cursor/skills/`, `.claude/skills/`):
+- List each skill directory name and its `description` from `SKILL.md`
+
+**Other config**:
+- `.documents-design/project.config.json` — platform, repo settings
+
+If no AI configuration exists, note this and produce a minimal output file focused on repository navigation only.
+
+### Step 2.5: Determine Target AI System
+
+Before generating any output, determine which AI system the user is targeting:
+
+| Trigger | Target system | Output file |
+|---------|--------------|-------------|
+| User says "create CLAUDE.md" or "for Claude Code" | Claude Code | `CLAUDE.md` |
+| `.claude/agents/` or `CLAUDE.md` already exists | Claude Code | `CLAUDE.md` |
+| User says "create AGENTS.md" or "for Copilot / Cursor" | GitHub Copilot or Cursor | `AGENTS.md` |
+| `.github/agents/` or `.cursor/agents/` already exists | GitHub Copilot or Cursor | `AGENTS.md` |
+| Both systems detected or ambiguous | Ask the user which file to generate | — |
+
+Carry this decision forward into Steps 4 and 5.
+
+### Step 3: Build Repository Classification
+
+Create a keyword-to-repository mapping for each repo. Derive keywords from:
+- Tech stack (e.g., React, Django, Spring Boot, Rust)
+- Domain (e.g., frontend, backend, API, testing, infrastructure)
+- File types (e.g., components, services, models, specs, manifests)
+- Tools (e.g., Webpack, Docker, Terraform, Playwright)
+
+### Step 4: Generate the Output File
+
+**Branch on the target AI system determined in Step 2.5:**
+
+#### Claude Code → generate `CLAUDE.md`
+
+Use the template at [templates/claude-md.template.md](templates/claude-md.template.md).
+
+Fill in each section with data collected in Steps 1–3. Follow these rules:
+
+1. **Project overview** — one paragraph describing the workspace purpose and repositories.
+2. **Repository layout** — ASCII tree (2–3 levels deep) with a short inline comment per repo.
+3. **Build & run commands** — for each repo, list the commands to install, build, test, and run. Read from `package.json`, `Makefile`, etc.
+4. **Code style & conventions** — infer from linter configs (`.eslintrc`, `pyproject.toml`, etc.) or note that they are project-defined.
+5. **Subagents** — if `.claude/agents/` exists, table of subagent name + purpose (one row per file, read `description` frontmatter).
+6. **Skills** — if `.claude/skills/` exists, table of skill name + purpose (one row per directory, read `description` from `SKILL.md`).
+7. **Specification & documentation rules** — if `.documents-design/` exists, document the folder convention, per-ticket artifacts table, and the rule that code changes without documentation updates are incomplete.
+8. **Working directory rules** — clarify which directory to `cd` into before running each command or making git commits.
+
+#### GitHub Copilot / Cursor → generate `AGENTS.md`
+
+Use the template at [templates/agents-md.template.md](templates/agents-md.template.md).
+
+Fill in each section by substituting `{{PLACEHOLDER}}` values with the data collected in Steps 1–3. Follow these rules:
+
+1. **Repository Structure tree** — render an ASCII tree showing the workspace layout. Include AI config directories with their contents. Show only key directories (2–3 levels deep) for each repo.
+
+2. **Working Directory Guidelines table** — one row per task type per repository. Derive task types from the repo's tech stack and purpose.
+
+3. **Git Operations** — include `cd` + git commands for each repo. Use the repo's conventional commit prefix (e.g., `feat:`, `test:`, `fix:`).
+
+4. **Package Management & Commands** — for each repository, create a titled subsection (e.g., `#### Dashboard (dashboard/)`) listing all available package manager commands grouped by category (install, development, testing, code quality). Read actual scripts from `package.json` or equivalent.
+
+5. **Specification & Documentation Rules** — if a `.documents-design/` folder exists:
+   - Document the folder convention (`.documents-design/features/{PARENT}/{CHILD}/`)
+   - Build the **Per-Ticket Artifacts** table mapping each artifact to its file path and the agent that creates it
+   - Build the **Per-Feature Artifacts** table for feature-level documents
+   - Include the AI Documentation Rule that code changes without documentation updates are incomplete
+
+6. **Context Switching** — reference the actual documentation paths found in Step 2.
+
+7. **Documentation Structure** — adapt based on the AI configuration detected in Step 2:
+   - Fill `{{AI_SYSTEM_DESCRIPTION}}` with a sentence describing which AI system(s) the project uses and their config paths (e.g., GitHub Copilot `.github/agents/`, Cursor `.cursor/agents/`, or both)
+   - Fill `{{AI_CONFIG_SECTIONS}}` with subsections for each detected config type:
+     - **Agents** table — one row per agent file with agent name and purpose. Use the heading that matches the system:
+       - GitHub Copilot → `### Custom Agents (.github/agents/)`
+       - Cursor → `### Agents (.cursor/agents/)`
+     - **Skills** paragraph — if `.github/skills/` or `.cursor/skills/` exists, describe that skills provide domain-specific knowledge invoked by agents
+   - If no AI configuration exists → omit the entire section
+
+8. **Common Workflows** — generate realistic, numbered-step workflows based on the repos' purposes (e.g., feature dev → implement + test + docs + feature docs + commit). Include agent invocation chains where applicable (e.g., `@web-auto-ticket-collector` → `@web-auto-test-cases-generator` → …).
+
+9. **Repository Identification Keywords** — use the classification from Step 3.
+
+### Step 5: Save and Confirm
+
+Save the generated file to the workspace root using the output filename determined in Step 2.5 (`CLAUDE.md` or `AGENTS.md`).
+
+If the target file already exists, ask the user:
+- **Overwrite** — replace entirely with the new version
+- **Update** — merge new information into the existing structure
+
+Present a summary of:
+- Which AI system was targeted and which file was generated
+- Repositories discovered
+- AI configuration cataloged (agents, skills, subagents)
+- Sections populated vs. omitted
+
+## Important Rules
+
+- ✅ Scan the actual workspace — never assume or fabricate repos/config
+- ✅ Adapt all sections to what is actually found; omit sections for things that don’t exist
+- ✅ Use relative paths from the workspace root in all references
+- ❌ Hardcode examples that were not discovered in the workspace
+- ❌ Guess or hallucinate — if something cannot be determined, omit it or flag it as unknown
+
+### Uncertainty & Hallucination Prevention
+
+The generated output file **must** include an "Uncertainty & Hallucination Prevention" section (see template) that instructs AI agents to:
+
+1. **Never fabricate** file paths, commands, configurations, or project details that were not verified in the workspace.
+2. **Stop and ask** the user for clarification when a task is ambiguous or the required context is missing — do not fill in gaps with assumptions.
+3. **Say "I don't know"** when they lack sufficient information rather than guessing.
+4. **Verify before acting** — confirm that files, directories, and commands actually exist before referencing or running them.
+5. **Clearly distinguish** between verified facts (discovered from the workspace) and inferences (derived from conventions or patterns), labeling any inferred information explicitly.

package/kits/shared/skills/workspace-ai-nav-creator/templates/agents-md.template.md

@@ -0,0 +1,112 @@
+# {{WORKSPACE_NAME}} Multi-Repository Workspace
+
+{{WORKSPACE_DESCRIPTION}}
+
+## Repository Structure
+
+```
+{{WORKSPACE_NAME}}/
+├── AGENTS.md                  # This file
+{{AI_CONFIG_TREE}}
+{{REPO_TREE}}
+{{SPECS_TREE}}
+```
+
+## AI Navigation Rules
+
+### Repository Detection
+Before performing any Git operations, file modifications, or running commands, the AI must:
+
+1. **Identify the target repository** based on the task context:
+{{REPO_DETECTION_LIST}}
+
+2. **Navigate to the correct repository directory**:
+   ```bash
+{{REPO_CD_EXAMPLES}}
+   ```
+
+### Working Directory Guidelines
+
+| Task Type | Repository | Working Directory | Examples |
+|-----------|------------|------------------|----------|
+{{WORKING_DIR_ROWS}}
+
+### Git Operations
+
+**CRITICAL**: Always `cd` to the appropriate repository before Git operations:
+
+```bash
+{{GIT_OPS_EXAMPLES}}
+```
+
+### Package Management & Commands
+
+Each repository has its own `package.json` and dependencies.
+
+{{PACKAGE_MGMT_SECTIONS}}
+
+## Specification & Documentation Rules
+
+**MANDATORY**: Every ticket implementation — whether writing code for any repository — **must** be accompanied by creating or updating the relevant documents in `.documents-design/`.
+
+### `.documents-design/` Folder Convention
+
+All ticket and feature documents live under:
+```
+.documents-design/features/{PARENT_FEATURE}/{CHILD_FEATURE}/
+```
+
+### Per-Ticket Artifacts
+
+| Artifact | File | Created By |
+|----------|------|------------|
+{{PER_TICKET_ARTIFACTS_ROWS}}
+
+### Per-Feature Artifacts
+
+| Artifact | File | Created/Updated By |
+|----------|------|--------------------|
+{{PER_FEATURE_ARTIFACTS_ROWS}}
+
+### AI Documentation Rule
+
+> **When implementing any ticket, the AI must always create or update the corresponding `.documents-design` documents alongside the code changes. Code changes without documentation updates are considered incomplete.**
+
+## Uncertainty & Hallucination Prevention
+
+AI agents operating in this workspace **must** follow these rules to avoid inaccurate outputs:
+
+1. **Do not guess** — If you are unsure about a file path, command, configuration value, or project detail, **stop and ask** the user instead of making an assumption.
+2. **Do not fabricate** — Never invent file names, directory structures, API endpoints, dependencies, or commands that you have not verified exist in the workspace.
+3. **Say "I don't know"** — When you lack the information needed to complete a task, explicitly state what is missing rather than filling gaps with plausible-sounding but unverified content.
+4. **Verify before acting** — Before running a command, referencing a file, or modifying configuration, confirm that the target actually exists (e.g., use `ls`, `find`, or file-search tools).
+5. **Label inferences** — If you derive something from conventions or patterns rather than direct workspace evidence, clearly mark it as an inference (e.g., _"Based on the project structure, this likely…"_).
+6. **Prefer omission over invention** — It is better to leave a section incomplete and flag it for the user than to populate it with hallucinated details.
+
+## Context Switching
+
+When switching between repositories during a conversation:
+
+1. **Explicitly state the repository change**:
+{{CONTEXT_SWITCH_EXAMPLES}}
+
+2. **Use the correct working directory** for all subsequent operations
+
+3. **Reference the appropriate documentation**:
+{{DOC_REFERENCES}}
+
+## Documentation Structure
+
+{{AI_SYSTEM_DESCRIPTION}}
+
+{{AI_CONFIG_SECTIONS}}
+
+## Common Workflows
+
+{{WORKFLOWS}}
+
+## Repository Identification Keywords
+
+{{REPO_KEYWORDS}}
+
+When these keywords appear in user requests, automatically navigate to the appropriate repository.

package/kits/shared/skills/workspace-ai-nav-creator/templates/claude-md.template.md

@@ -0,0 +1,86 @@
+# {{WORKSPACE_NAME}}
+
+{{WORKSPACE_DESCRIPTION}}
+
+## Repository Layout
+
+```
+{{WORKSPACE_NAME}}/
+├── CLAUDE.md                  # This file — Claude Code project instructions
+{{AI_CONFIG_TREE}}
+{{REPO_TREE}}
+{{SPECS_TREE}}
+```
+
+## Working Directory Rules
+
+**CRITICAL**: Always `cd` to the correct repository before running commands or making Git commits.
+
+{{REPO_CD_EXAMPLES}}
+
+| Task | Repository | Working Directory |
+|------|------------|------------------|
+{{WORKING_DIR_ROWS}}
+
+## Build & Run Commands
+
+{{PACKAGE_MGMT_SECTIONS}}
+
+## Git Operations
+
+Use `cd` to navigate to the correct repository before any Git operation:
+
+```bash
+{{GIT_OPS_EXAMPLES}}
+```
+
+## Code Style & Conventions
+
+{{CODE_STYLE_SECTIONS}}
+
+## Specification & Documentation Rules
+
+**MANDATORY**: Every ticket implementation **must** be accompanied by creating or updating the relevant documents in `.documents-design/`.
+
+### `.documents-design/` Folder Convention
+
+```
+.documents-design/features/{PARENT_FEATURE}/{CHILD_FEATURE}/
+```
+
+### Per-Ticket Artifacts
+
+| Artifact | File | Created By |
+|----------|------|------------|
+{{PER_TICKET_ARTIFACTS_ROWS}}
+
+### Per-Feature Artifacts
+
+| Artifact | File | Created/Updated By |
+|----------|------|--------------------|
+{{PER_FEATURE_ARTIFACTS_ROWS}}
+
+> **Code changes without documentation updates are considered incomplete.**
+
+## Claude Code Subagents
+
+{{CLAUDE_AGENTS_DESCRIPTION}}
+
+| Subagent | Purpose |
+|----------|---------|
+{{CLAUDE_AGENTS_ROWS}}
+
+## Repository Identification Keywords
+
+{{REPO_KEYWORDS}}
+
+When these keywords appear in user requests, automatically navigate to the appropriate repository.
+
+## Uncertainty & Hallucination Prevention
+
+1. **Do not guess** — If you are unsure about a file path, command, or project detail, stop and ask the user.
+2. **Do not fabricate** — Never invent file names, directories, API endpoints, or commands you have not verified exist.
+3. **Say "I don't know"** — Explicitly state what is missing rather than filling gaps with plausible-sounding content.
+4. **Verify before acting** — Confirm that files, directories, and commands actually exist before referencing or running them.
+5. **Label inferences** — If you derive something from conventions rather than direct evidence, mark it as an inference.
+6. **Prefer omission over invention** — Leave a section incomplete and flag it rather than populate it with hallucinated details.

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "evizi-kit",
+  "version": "1.0.0",
+  "description": "Multi-agent development kit supporting Claude Code, Cursor, GitHub Copilot, and more.",
+  "files": [
+    "kits/"
+  ],
+  "keywords": [
+    "claude-code",
+    "cursor",
+    "github-copilot",
+    "windsurf",
+    "ai-agents"
+  ],
+  "license": "MIT"
+}