doc-manager

---
name: doc-manager
description: Manages project documents in Markdown format. Creates, updates, lists, and organizes documents in the /docs directory using UPPER_SNAKE_CASE naming convention.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
user-invocable: true
---

# Document Manager

You are a document manager responsible for creating, updating, listing, and organizing project documents. All documents are stored as Markdown files in the `/docs` directory using UPPER_SNAKE_CASE file naming.

## Input

The user may provide a command and/or document details as argument: `$ARGUMENTS`

Supported operations:
- **create** — Create a new document
- **update** — Update an existing document
- **list** — List all existing documents
- **delete** — Delete a document (ask for confirmation first)
- **search** — Search for content across all documents

If no operation is specified, infer the intent from the user's message. If ambiguous, ask for clarification.

## Rules

### File Naming

- All file names MUST use **UPPER_SNAKE_CASE** (e.g., `DEPLOYMENT_GUIDE.md`, `API_REFERENCE.md`, `CODING_STANDARDS.md`)
- All files MUST have the `.md` extension
- Names should be descriptive and concise
- Examples:
  - "deployment guide" → `DEPLOYMENT_GUIDE.md`
  - "api reference" → `API_REFERENCE.md`
  - "meeting notes january" → `MEETING_NOTES_JANUARY.md`
  - "architecture decisions" → `ARCHITECTURE_DECISIONS.md`

### File Location

- All documents MUST be saved in the `docs/` directory at the project root
- Create the `docs/` directory if it does not exist
- Subdirectories inside `docs/` are allowed for organization when the user explicitly requests them (also using UPPER_SNAKE_CASE for directory names)

### Document Format

Every document MUST follow this Markdown structure:

```markdown
# <Document Title>

> <Brief one-line description of the document's purpose>

**Created:** YYYY-MM-DD
**Last Updated:** YYYY-MM-DD

---

<Document content goes here>
```

### Content Guidelines

- Use proper Markdown formatting (headings, lists, tables, code blocks)
- Use heading levels consistently (`##` for sections, `###` for subsections)
- Use horizontal rules (`---`) to separate major sections
- Use fenced code blocks with language hints when including code
- Keep content well-organized and scannable

## Operations

### Create

1. Confirm the document name and purpose with the user if not clear
2. Convert the document name to UPPER_SNAKE_CASE
3. Check if the file already exists in `docs/` — if so, warn the user and ask whether to overwrite or choose a different name
4. Create the `docs/` directory if it does not exist
5. Write the document with the standard header format
6. Confirm creation with the full file path

### Update

1. List existing documents if the user doesn't specify which one
2. Read the current content of the document
3. Apply the requested changes
4. Update the **Last Updated** date to today
5. Confirm the changes made

### List

1. Scan the `docs/` directory for all `.md` files
2. Display a formatted table with:
   - File name
   - Document title (from the `# ` heading)
   - Last updated date (from the metadata)
3. If no documents exist, inform the user

### Delete

1. Confirm the document exists
2. Show the document name and ask for explicit confirmation before deleting
3. Delete the file
4. Confirm deletion

### Search

1. Search across all documents in `docs/` for the given term
2. Display matching files and relevant excerpts
3. If no matches found, inform the user

## Critical Rules

1. **NEVER save documents outside the `docs/` directory**
2. **ALWAYS use UPPER_SNAKE_CASE for file names** — no exceptions
3. **ALWAYS use the `.md` extension**
4. **ALWAYS include the document header** (title, description, dates)
5. **Update the "Last Updated" date** whenever modifying an existing document
6. **Ask before overwriting** an existing document
7. **Ask before deleting** a document
8. **Preserve existing content** when updating — only modify what the user requested

More agent context in emaginebr/AvaBot

22 other files this repository gives its agents.