docs-manager-skill

**Purpose**: Orchestrate complete single-document workflows with automatic validation and indexing.

Architecture: Coordination skill (Layer 2) - manages write → validate → index pipeline for single documents.

Scope: ONE document at a time (director handles multi-doc operations).

1. **Single Document Focus** - ALWAYS operate on exactly ONE document - NEVER handle wildcards or patterns (that's docs-director-skill's job)

1. Workflow Coordination

   • ALWAYS execute: write → validate → index (3-phase pipeline)
   • NEVER skip validation unless explicitly requested
   • ALWAYS update index after successful write+validate

2. Type Context Loading

   • ALWAYS load type context before operations
   • NEVER proceed without valid doc_type

3. Error Handling

   • STOP immediately on validation errors
   • REPORT all failures clearly
   • ROLLBACK if index update fails (delete written file)

4. Operation Skills

   • ALWAYS use operation skills (doc-writer, doc-validator, doc-lister)
   • NEVER implement operations directly

**Required**: - `operation` - Operation type: "write", "update", "validate", "index" - `file_path` - Target document path

For write/update:

• doc_type OR auto-detect from path/content
• context - Conversational context (what user wants)
• template_data - Explicit template variables (optional)
• skip_validation - Skip validation step (default: false)
• skip_index - Skip index update (default: false)

For validate:

• doc_type OR auto-detect

For index:

• doc_type - Required
• directory - Directory to index (default: parent of file_path)

## Operation: write

1. Classify Document Type

   • If doc_type provided: use it
   • Else: invoke doc-classifier skill to auto-detect from path

2. Load Type Context

   • Load schema.json, template.md, standards.md from types/{doc_type}/
   • Build context bundle: conversational + type-specific + template_data

3. Invoke doc-writer Skill

   • Pass: file_path, doc_type, context bundle
   • Receive: written file path

4. Validate Document (unless skip_validation=true)

   • Invoke doc-validator skill
   • Pass: file_path, doc_type
   • If validation fails: STOP, report errors
   • If validation succeeds: continue

5. Update Index (unless skip_index=true)

   • Determine directory from file_path
   • Invoke index-updater.sh script
   • Pass: directory, doc_type

6. Return Success

   {
     "status": "success",
     "operation": "write",
     "file_path": "docs/api/user-login/README.md",
     "doc_type": "api",
     "validation": "passed",
     "index_updated": true
   }
   

Operation: update

Same as write, but:

• Read existing file first
• Merge existing content with new context
• Bump version if version field exists

Operation: validate

1. Classify Document Type

   • Auto-detect if not provided

2. Invoke doc-validator Skill

   • Pass: file_path, doc_type
   • Return validation results

Operation: index

1. Invoke index-updater.sh
   • Pass: directory, doc_type
   • Return index update status

- Document written successfully (for write/update) - Validation passed (unless skipped) - Index updated (unless skipped) - All operation skills invoked correctly - Clear success/failure status returned **Success**: ```json { "status": "success", "operation": "write|update|validate|index", "file_path": "path/to/file", "doc_type": "api", "validation": "passed|skipped|failed", "index_updated": true|false, "artifacts": ["README.md", "endpoint.json"] } ```

Failure:

{
  "status": "error",
  "operation": "write|update|validate|index",
  "error": "Validation failed: missing required field 'endpoint'",
  "file_path": "path/to/file",
  "validation_errors": ["error1", "error2"]
}

Output structured messages:

Start:

🎯 STARTING: docs-manager-skill
Operation: write
File: docs/api/user-login/README.md
Doc Type: api
───────────────────────────────────────

During Execution:

Step 1/5: Classifying document type...
   ✅ Detected: api (confidence: 100, method: path)

Step 2/5: Loading type context...
   ✅ Loaded: schema.json, template.md, standards.md

Step 3/5: Writing document...
   ✅ Generated: docs/api/user-login/README.md

Step 4/5: Validating document...
   ✅ Validation passed (0 errors, 0 warnings)

Step 5/5: Updating index...
   ✅ Index updated: docs/api/README.md

Completion:

✅ COMPLETED: docs-manager-skill
Operation: write
File: docs/api/user-login/README.md
Artifacts:
  - docs/api/user-login/README.md
  - docs/api/README.md (index)
───────────────────────────────────────
Next: Document ready for review

**Validation Errors**: - Stop pipeline immediately - Report all validation errors - Do NOT update index - Do NOT delete written file (user may want to fix manually)

Index Update Errors:

• Report error
• Document is still valid (validation passed)
• Suggest manual index update

Type Detection Errors:

• Cannot proceed without valid doc_type
• Suggest manual doc_type specification
• List available doc_types

Script Execution Errors:

• Report script path and error message
• Suggest checking script permissions
• Provide command to run script manually for debugging