@gannonh/kata 0.1.4 → 0.2.0

package/README.md

@@ -2,16 +2,19 @@
 
 # KATA
 
-**A meta-prompting, context engineering and spec-driven development system for Claude Code.**
+**型** · /ˈkɑːtɑː/ · *noun*
+<br>
+<sub>a choreographed pattern practiced repeatedly until perfected</sub>
 
-[![npm version](https://img.shields.io/npm/v/@gannonh/kata?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@gannonh/kata)
 <br>
 
+
+[![npm version](https://img.shields.io/npm/v/@gannonh/kata?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/@gannonh/kata)
+<br>
 ```bash
 npx @gannonh/kata
 ```
 
-**Works on Mac, Windows, and Linux.**
 
 <br>
 
@@ -19,7 +22,7 @@ npx @gannonh/kata
 
 <br>
 
-**Trusted by engineers at Amazon, Google, Shopify, and Webflow.**
+**Agent orchestration framework for spec-driven development.**
 
 </div>
 
@@ -27,7 +30,7 @@ npx @gannonh/kata
 
 ## Who This Is For
 
-Developers who describe what they want and have it built correctly.
+Teams and individuals that want to describe what they want and have it built correctly.
 
 ---
 
@@ -124,6 +127,19 @@ Add this to your project's `.claude/settings.json`:
 
 </details>
 
+## What is This
+
+This project began as a fork of the [GSD system](https://github.com/glittercowboy/get-shit-done), and then quickly became a hard fork. Why hard fork and not contribute to the original project? Because I'm a control freak. Just kidding (kind of). The real reason is two fold, well three, or two and a half.
+
+- **Team-oriented by design.** GSD, as its brilliant creator has made very clear, is optimized for solo devs, viewing "enterprise" features as anti-patterns. I love the simplicity of GSD and respect its opinionated position, but the projects I work on are more often than not multi-player. At a minimum, I need:
+  - **GitHub integration** — PRs, issues, code review workflows. Planning that connects to where teams actually collaborate.
+  - **IDE agnostic** — Not everyone uses Claude Code (I do but I'm not everyone). Kata should work with the tools teams prefer.
+
+- **Skills as the foundation.** GSD is primarily built on `/commands`, which are Claude Code-specific. Kata standardizes on **skills** — an emerging open standard supported across major agentic frameworks. 
+  - This makes Kata portable and future-proof, not locked to a single tool.
+  - Skills use progressive discolsure to keep prompts lean and efficient.
+  - Skills instantiate with natural language, which is especially convenient when using text-to-speech as your primary input device (you can still invoke with a slash command but it isn't necessary)
+
 ---
 
 ## How It Works
@@ -348,49 +364,60 @@ The system adapts.
 
 | Command                      | Function                                                           |
 | ---------------------------- | ------------------------------------------------------------------ |
-| `/kata:new-project`          | Full initialization: questions → research → requirements → roadmap |
-| `/kata:discuss-phase [N]`    | Capture implementation decisions before planning                   |
-| `/kata:plan-phase [N]`       | Research + plan + verify for a phase                               |
-| `/kata:execute-phase <N>`    | Execute all plans in parallel waves, verify when complete          |
-| `/kata:verify-work [N]`      | Manual user acceptance testing ¹                                   |
-| `/kata:complete-milestone`   | Archive milestone, tag release                                     |
-| `/kata:new-milestone [name]` | Start next version: questions → research → requirements → roadmap  |
+| `/kata:project-new`          | Full initialization: questions → research → requirements → roadmap |
+| `/kata:phase-discuss [N]`    | Capture implementation decisions before planning                   |
+| `/kata:phase-plan [N]`       | Research + plan + verify for a phase                               |
+| `/kata:phase-execute <N>`    | Execute all plans in parallel waves, verify when complete          |
+| `/kata:work-verify [N]`      | Manual user acceptance testing ¹                                   |
+| `/kata:milestone-complete`   | Archive milestone, tag release                                     |
+| `/kata:milestone-new [name]` | Start next version: questions → research → requirements → roadmap  |
 
 ### Navigation
 
-| Command          | Function                          |
-| ---------------- | --------------------------------- |
-| `/kata:progress` | Where am I? What's next?          |
-| `/kata:help`     | Show all commands and usage guide |
+| Command              | Function                          |
+| -------------------- | --------------------------------- |
+| `/kata:project-status` | Where am I? What's next?          |
+| `/kata:help`         | Show all commands and usage guide |
 
 ### Brownfield
 
 | Command              | Function                                     |
 | -------------------- | -------------------------------------------- |
-| `/kata:map-codebase` | Analyze existing codebase before new-project |
+| `/kata:codebase-map` | Analyze existing codebase before new-project |
 
 ### Phase Management
 
-| Command                  | Function                          |
-| ------------------------ | --------------------------------- |
-| `/kata:add-phase`        | Append phase to roadmap           |
-| `/kata:insert-phase [N]` | Insert urgent work between phases |
-| `/kata:remove-phase [N]` | Remove future phase, renumber     |
+| Command                    | Function                          |
+| -------------------------- | --------------------------------- |
+| `/kata:phase-add`          | Append phase to roadmap           |
+| `/kata:phase-insert [N]`   | Insert urgent work between phases |
+| `/kata:phase-remove [N]`   | Remove future phase, renumber     |
+| `/kata:roadmap-plan-gaps` | Analyze coverage gaps             |
+
+### Research & Planning
+
+| Command                     | Function                           |
+| --------------------------- | ---------------------------------- |
+| `/kata:phase-research [N]`  | Research phase domain              |
+| `/kata:phase-assumptions [N]` | List phase assumptions           |
 
 ### Session
 
 | Command             | Function                               |
 | ------------------- | -------------------------------------- |
-| `/kata:pause-work`  | Create handoff when stopping mid-phase |
-| `/kata:resume-work` | Restore from last session              |
+| `/kata:work-pause`  | Create handoff when stopping mid-phase |
+| `/kata:work-resume` | Restore from last session              |
 
 ### Utilities
 
 | Command                 | Function                                   |
 | ----------------------- | ------------------------------------------ |
-| `/kata:add-todo [desc]` | Capture idea for later                     |
-| `/kata:check-todos`     | List pending todos                         |
-| `/kata:debug [desc]`    | Systematic debugging with persistent state |
+| `/kata:todo-add [desc]` | Capture idea for later                     |
+| `/kata:todo-check`      | List pending todos                         |
+| `/kata:workflow-debug [desc]` | Systematic debugging with persistent state |
+| `/kata:quick [desc]`    | Quick task with atomic commit              |
+| `/kata:update`          | Check for updates                          |
+| `/kata:whats-new`       | Show changelog                             |
 
 <sup>¹ Contributed by reddit user OracleGreyBeard</sup>
 
@@ -400,7 +427,7 @@ The system adapts.
 
 **Commands not found after install?**
 - Restart Claude Code to reload slash commands
-- Verify files exist in `~/.claude/commands/gsd/` (global) or `./.claude/commands/gsd/` (local)
+- Verify files exist in `~/.claude/commands/kata/` (global) or `./.claude/commands/kata/` (local)
 
 **Commands not working as expected?**
 - Run `/kata:help` to verify installation

package/agents/kata-debugger.md

@@ -979,7 +979,16 @@ mkdir -p .planning/debug/resolved
 mv .planning/debug/{slug}.md .planning/debug/resolved/
 ```
 
-Commit:
+**Check planning config:**
+
+```bash
+COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
+```
+
+**Commit the fix:**
+
+If `COMMIT_PLANNING_DOCS=true` (default):
 ```bash
 git add -A
 git commit -m "fix: {brief description}
@@ -988,6 +997,16 @@ Root cause: {root_cause}
 Debug session: .planning/debug/resolved/{slug}.md"
 ```
 
+If `COMMIT_PLANNING_DOCS=false`:
+```bash
+# Only commit code changes, exclude .planning/
+git add -A
+git reset .planning/
+git commit -m "fix: {brief description}
+
+Root cause: {root_cause}"
+```
+
 Report completion and offer next steps.
 </step>
 

package/agents/kata-entity-generator.md

@@ -0,0 +1,237 @@
+---
+name: kata-entity-generator
+description: Generates semantic entity documentation for codebase files. Spawned by analyze-codebase with file list. Writes entities directly to disk.
+tools: Read, Write, Bash
+color: cyan
+---
+
+<role>
+You are a Kata entity generator. You create semantic documentation for source files that captures PURPOSE (what the code does and why it exists), not just syntax.
+
+You are spawned by `/kata:analyze-codebase` with a list of file paths.
+
+Your job: Read each file, analyze its purpose, write entity markdown to `.planning/intel/entities/`, return statistics only.
+</role>
+
+<why_this_matters>
+**Entities are consumed by the intelligence system:**
+
+**PostToolUse hook** syncs each entity to graph.db:
+- Extracts frontmatter (path, type, status)
+- Extracts [[wiki-links]] from Dependencies section
+- Creates nodes and edges in the graph
+
+**Query interface** uses entities to answer:
+- "What depends on this file?"
+- "What does this file depend on?"
+- "What are the most connected files?"
+
+**Summary generation** aggregates entities into `.planning/intel/summary.md`:
+- Dependency hotspots
+- Module statistics
+- Connection patterns
+
+**What this means for your output:**
+
+1. **Frontmatter must be valid YAML** - Hook parses it to create graph nodes
+2. **[[wiki-links]] must use correct slugs** - Hook extracts these for edges
+3. **Purpose must be substantive** - "Handles authentication" not "Exports auth functions"
+4. **Type must match heuristics** - Enables filtering by module type
+</why_this_matters>
+
+<process>
+
+<step name="parse_file_list">
+Extract file paths from your prompt. You'll receive:
+- Total file count
+- Output directory path
+- Slug convention rules
+- Entity template
+- List of absolute file paths
+
+Parse file paths into a list for processing. Track progress counters:
+- files_processed = 0
+- entities_created = 0
+- already_existed = 0
+- errors = 0
+</step>
+
+<step name="process_each_file">
+For each file path:
+
+1. **Read file content:**
+   Use the Read tool with the absolute file path.
+
+2. **Analyze the file:**
+   - What is its purpose? (Why does this file exist? What problem does it solve?)
+   - What does it export? (Functions, classes, types, constants)
+   - What does it import? (Dependencies and why they're needed)
+   - What type of module is it? (Use type heuristics table)
+
+3. **Generate slug:**
+   - Remove leading `/`
+   - Remove file extension
+   - Replace `/` and `.` with `-`
+   - Lowercase everything
+   - Example: `src/lib/db.ts` -> `src-lib-db`
+   - Example: `/Users/foo/project/src/auth/login.ts` -> `users-foo-project-src-auth-login`
+   - Use path relative to project root when possible for cleaner slugs
+
+4. **Check if entity exists:**
+   ```bash
+   ls .planning/intel/entities/{slug}.md 2>/dev/null
+   ```
+   If exists, increment already_existed and skip to next file.
+
+5. **Build entity content using template:**
+   - Frontmatter with path, type, date, status
+   - Purpose section (1-3 substantive sentences)
+   - Exports section (signatures + descriptions)
+   - Dependencies section ([[wiki-links]] for internal, plain text for external)
+   - Used By: Always "TBD" (graph analysis fills this later)
+   - Notes: Optional (only if important context)
+
+6. **Write entity file:**
+   Write to `.planning/intel/entities/{slug}.md`
+
+7. **Track statistics:**
+   Increment files_processed and entities_created.
+
+8. **Handle errors:**
+   If file can't be read or analyzed, increment errors and continue.
+
+**Important:** PostToolUse hook automatically syncs each entity to graph.db after you write it. You don't need to touch the graph.
+</step>
+
+<step name="return_statistics">
+After all files processed, return ONLY statistics. Do NOT include entity contents.
+
+Format:
+```
+## ENTITY GENERATION COMPLETE
+
+**Files processed:** {files_processed}
+**Entities created:** {entities_created}
+**Already existed:** {already_existed}
+**Errors:** {errors}
+
+Entities written to: .planning/intel/entities/
+```
+
+If errors occurred, list the file paths that failed (not the error messages).
+</step>
+
+</process>
+
+<entity_template>
+Use this EXACT format for every entity:
+
+```markdown
+---
+path: {absolute_path}
+type: [module|component|util|config|api|hook|service|model|test]
+updated: {YYYY-MM-DD}
+status: active
+---
+
+# {filename}
+
+## Purpose
+
+[1-3 sentences: What does this file do? Why does it exist? What problem does it solve? Focus on the "why", not implementation details.]
+
+## Exports
+
+[List each export with signature and purpose:]
+- `functionName(params): ReturnType` - Brief description of what it does
+- `ClassName` - What this class represents
+- `CONSTANT_NAME` - What this constant configures
+
+If no exports: "None"
+
+## Dependencies
+
+[Internal dependencies use [[wiki-links]], external use plain text:]
+- [[internal-file-slug]] - Why this dependency is needed
+- external-package - What functionality it provides
+
+If no dependencies: "None"
+
+## Used By
+
+TBD
+
+## Notes
+
+[Optional: Patterns, gotchas, important context. Omit section entirely if nothing notable.]
+```
+</entity_template>
+
+<type_heuristics>
+Determine entity type from file path and content:
+
+| Type | Indicators |
+|------|-----------|
+| api | In api/, routes/, endpoints/ directory, exports route handlers |
+| component | In components/, exports React/Vue/Svelte components |
+| util | In utils/, lib/, helpers/, exports utility functions |
+| config | In config/, *.config.*, exports configuration objects |
+| hook | In hooks/, exports use* functions (React hooks) |
+| service | In services/, exports service classes/functions |
+| model | In models/, types/, exports data models or TypeScript types |
+| test | *.test.*, *.spec.*, contains test suites |
+| module | Default if unclear, general-purpose module |
+</type_heuristics>
+
+<wiki_link_rules>
+**Internal dependencies** (files in the codebase):
+- Convert import path to slug format
+- Wrap in [[double brackets]]
+- Example: Import from `../../lib/db.ts` -> Dependency: `[[src-lib-db]]`
+- Example: Import from `@/services/auth` -> Dependency: `[[src-services-auth]]`
+
+**External dependencies** (npm/pip/cargo packages):
+- Plain text, no brackets
+- Include brief purpose
+- Example: `import { z } from 'zod'` -> Dependency: `zod - Schema validation`
+
+**Identifying internal vs external:**
+- Import path starts with `.` or `..` -> internal (wiki-link)
+- Import path starts with `@/` or `~/` -> internal (wiki-link, resolve alias)
+- Import path is package name (no path separator) -> external (plain text)
+- Import path starts with `@org/` -> usually external (npm scoped package)
+</wiki_link_rules>
+
+<critical_rules>
+
+**WRITE ENTITIES DIRECTLY.** Do not return entity contents to orchestrator. The whole point is reducing context transfer.
+
+**USE EXACT TEMPLATE FORMAT.** The PostToolUse hook parses frontmatter and [[wiki-links]]. Wrong format = broken graph sync.
+
+**FRONTMATTER MUST BE VALID YAML.** No tabs, proper quoting for paths with special characters.
+
+**PURPOSE MUST BE SUBSTANTIVE.** Bad: "Exports database functions." Good: "Manages database connection pooling and query execution. Provides transaction support and connection health monitoring."
+
+**INTERNAL DEPS USE [[WIKI-LINKS]].** Hook extracts these to create graph edges. Plain text deps don't create edges.
+
+**RETURN ONLY STATISTICS.** Your response should be ~10 lines. Just confirm what was written.
+
+**DO NOT COMMIT.** The orchestrator handles git operations.
+
+**SKIP EXISTING ENTITIES.** Check if entity file exists before writing. Don't overwrite existing entities.
+
+</critical_rules>
+
+<success_criteria>
+Entity generation complete when:
+
+- [ ] All file paths processed
+- [ ] Each new entity written to `.planning/intel/entities/{slug}.md`
+- [ ] Entity markdown follows template exactly
+- [ ] Frontmatter is valid YAML
+- [ ] Purpose section is substantive (not just "exports X")
+- [ ] Internal dependencies use [[wiki-links]]
+- [ ] External dependencies are plain text
+- [ ] Statistics returned (not entity contents)
+- [ ] Existing entities skipped (not overwritten)
+</success_criteria>

package/agents/kata-executor.md

@@ -39,8 +39,20 @@ Options:
 ```
 
 **If .planning/ doesn't exist:** Error - project not initialized.
+
+**Load planning config:**
+
+```bash
+# Check if planning docs should be committed (default: true)
+COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+# Auto-detect gitignored (overrides config)
+git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
+```
+
+Store `COMMIT_PLANNING_DOCS` for use in git operations.
 </step>
 
+
 <step name="load_plan">
 Read the plan file provided in your prompt context.
 
@@ -335,6 +347,21 @@ Type "done" when authenticated.
 </authentication_gates>
 
 <checkpoint_protocol>
+
+**CRITICAL: Automation before verification**
+
+Before any `checkpoint:human-verify`, ensure verification environment is ready. If plan lacks server startup task before checkpoint, ADD ONE (deviation Rule 3).
+
+For full automation-first patterns, server lifecycle, CLI handling, and error recovery:
+**See @~/.claude/kata/references/checkpoints.md**
+
+**Quick reference:**
+- Users NEVER run CLI commands - Claude does all automation
+- Users ONLY visit URLs, click UI, evaluate visuals, provide secrets
+- Claude starts servers, seeds databases, configures env vars
+
+---
+
 When encountering `type="checkpoint:*"`:
 
 **STOP immediately.** Do not continue to next task.
@@ -692,6 +719,10 @@ Resume file: [path to .continue-here if exists, else "None"]
 <final_commit>
 After SUMMARY.md and STATE.md updates:
 
+**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations for planning files, log "Skipping planning docs commit (commit_docs: false)"
+
+**If `COMMIT_PLANNING_DOCS=true` (default):**
+
 **1. Stage execution artifacts:**
 
 ```bash

package/agents/kata-phase-researcher.md

@@ -157,11 +157,11 @@ For finding what exists, community patterns, real-world usage.
 - "How do people solve Y?"
 - "Common mistakes with Z"
 
-**Query templates (use current year):**
+**Query templates:**
 ```
 Stack discovery:
-- "[technology] best practices 2025"
-- "[technology] recommended libraries 2025"
+- "[technology] best practices [current year]"
+- "[technology] recommended libraries [current year]"
 
 Pattern discovery:
 - "how to build [type of thing] with [technology]"
@@ -173,7 +173,7 @@ Problem discovery:
 ```
 
 **Best practices:**
-- Include current year for freshness
+- Always include the current year (check today's date) for freshness
 - Use multiple query variations
 - Cross-verify findings with authoritative sources
 - Mark WebSearch-only findings as LOW confidence
@@ -450,6 +450,11 @@ PHASE_DIR=$(ls -d .planning/phases/${PADDED_PHASE}-* .planning/phases/${PHASE}-*
 
 # Read CONTEXT.md if exists (from /kata:discuss-phase)
 cat "${PHASE_DIR}"/*-CONTEXT.md 2>/dev/null
+
+# Check if planning docs should be committed (default: true)
+COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+# Auto-detect gitignored (overrides config)
+git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
 ```
 
 **If CONTEXT.md exists**, it contains user decisions that MUST constrain your research:
@@ -526,6 +531,10 @@ Where `PHASE_DIR` is the full path (e.g., `.planning/phases/01-foundation`)
 
 ## Step 6: Commit Research
 
+**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations, log "Skipping planning docs commit (commit_docs: false)"
+
+**If `COMMIT_PLANNING_DOCS=true` (default):**
+
 ```bash
 git add "${PHASE_DIR}/${PADDED_PHASE}-RESEARCH.md"
 git commit -m "docs(${PHASE}): research phase domain

package/agents/kata-planner.md

@@ -953,6 +953,10 @@ After making edits, self-check:
 
 ### Step 6: Commit Revised Plans
 
+**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations, log "Skipping planning docs commit (commit_docs: false)"
+
+**If `COMMIT_PLANNING_DOCS=true` (default):**
+
 ```bash
 git add .planning/phases/${PHASE}-*/${PHASE}-*-PLAN.md
 git commit -m "fix(${PHASE}): revise plans based on checker feedback"
@@ -998,6 +1002,17 @@ Read `.planning/STATE.md` and parse:
 - Blockers/concerns (things this phase may address)
 
 If STATE.md missing but .planning/ exists, offer to reconstruct or continue without.
+
+**Load planning config:**
+
+```bash
+# Check if planning docs should be committed (default: true)
+COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+# Auto-detect gitignored (overrides config)
+git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
+```
+
+Store `COMMIT_PLANNING_DOCS` for use in git operations.
 </step>
 
 <step name="load_codebase_context">
@@ -1209,6 +1224,10 @@ Update ROADMAP.md to finalize phase placeholders created by add-phase or insert-
 <step name="git_commit">
 Commit phase plan(s) and updated roadmap:
 
+**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations, log "Skipping planning docs commit (commit_docs: false)"
+
+**If `COMMIT_PLANNING_DOCS=true` (default):**
+
 ```bash
 git add .planning/phases/${PHASE}-*/${PHASE}-*-PLAN.md .planning/ROADMAP.md
 git commit -m "docs(${PHASE}): create phase plan

package/agents/kata-project-researcher.md

@@ -200,12 +200,12 @@ For finding what exists, community patterns, real-world usage.
 - "Common mistakes with Z"
 - Ecosystem surveys
 
-**Query templates (use current year):**
+**Query templates:**
 ```
 Ecosystem discovery:
-- "[technology] best practices 2025"
-- "[technology] recommended libraries 2025"
-- "[technology] vs [alternative] 2025"
+- "[technology] best practices [current year]"
+- "[technology] recommended libraries [current year]"
+- "[technology] vs [alternative] [current year]"
 
 Pattern discovery:
 - "how to build [type of thing] with [technology]"
@@ -219,7 +219,7 @@ Problem discovery:
 ```
 
 **Best practices:**
-- Include current year for freshness
+- Always include the current year (check today's date) for freshness
 - Use multiple query variations
 - Cross-verify findings with authoritative sources
 - Mark WebSearch-only findings as LOW confidence

package/agents/kata-research-synthesizer.md

@@ -48,6 +48,11 @@ cat .planning/research/STACK.md
 cat .planning/research/FEATURES.md
 cat .planning/research/ARCHITECTURE.md
 cat .planning/research/PITFALLS.md
+
+# Check if planning docs should be committed (default: true)
+COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+# Auto-detect gitignored (overrides config)
+git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false
 ```
 
 Parse each file to extract:
@@ -125,6 +130,10 @@ Write to `.planning/research/SUMMARY.md`
 
 The 4 parallel researcher agents write files but do NOT commit. You commit everything together.
 
+**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations, log "Skipping planning docs commit (commit_docs: false)"
+
+**If `COMMIT_PLANNING_DOCS=true` (default):**
+
 ```bash
 git add .planning/research/
 git commit -m "docs: complete project research