================================================================================
                           CODEX PROMPTS REFERENCE
================================================================================

This directory contains specialized prompts for structured software development
workflows. Commands are organized by category for clarity.

Requirements:
  [Nia MCP] <trynia.ai>
    - If not, grep "nia" and remove all references, or replace with Context7

================================================================================
                             WORKFLOW DIRECTIONS
================================================================================

----------------------
| GREENFIELD EXAMPLE |
----------------------

Let's say you want to add a new feature that allows users to authenticate via
Google OAuth. The workflow is as follows:

   requirements --> design --> tasks --> implementation --> cleanup

An example looks like:

1. /spec:new "add-google-auth"
2. /spec:requirements "create" "Add google oauth for all users, handle DB migrations, etc."
   Looks good? --> /spec:approve requirements
   Need adjustments? --> /spec:requirements "update" "ensure fallback for email/pass"
3. /spec:design "create" "[CONTEXT]"  # Background research --> design doc
   Looks good --> /spec:approve "design"
   ...
4. Context window is slimming down, run /spec:handoff then start a new agent thread with the handoff prompt.
5. /spec:tasks "create" "[CONTEXT]"   # Using design doc + more docs --> tasks doc
   Looks Good? --> /spec:approve "tasks" ...
   Need docs? --> /spec:tasks "docs" "Investigate the docs for google oauth with XYZ MCP"
6. /spec:implement-next  (strict adherence to docs & single phase implementation)
   -OR-
   /spec:implement       (for more creative implementation)
7. Context window is slimming down, run /spec:handoff ...
8. /spec:implement-next
9. In a new agent thread, run /spec:cleanup  # Verifies everything, builds, tests, etc.

================================================================================
                                    COMMANDS
================================================================================

--------------------------
| SPECIFICATION WORKFLOW |
--------------------------

  /spec:new <feature-name>
    Create a new feature specification with auto-incremented ID.
    Example: /spec:new user-authentication

  /spec:requirements {create|review|update} [context]
    Manage requirements specification documents.
    - create:  Generate initial requirements from template
    - review:  Evaluate completeness and identify gaps
    - update:  Apply contextual changes to existing requirements

  /spec:design {create|review|update} [context]
    Manage technical design specifications.
    - create:  Produce architecture and implementation design
    - review:  Assess design decisions and alignment with requirements
    - update:  Revise design based on new constraints or feedback

  /spec:tasks {create|review|update|docs} [context]
    Manage implementation task lists with phase breakdown.
    - create:  Generate phased task list with estimates and dependencies
    - review:  Validate task coverage, sequencing, and risk handling
    - update:  Modify tasks and update implementation logs
    - docs:    Query and attach documentation sources to task items

  /spec:approve {requirements|design|tasks}
    Create approval marker for completed specification phase.
    Automatically suggests next phase in workflow.

---------------------------
| IMPLEMENTATION WORKFLOW |
---------------------------

  /spec:implement [phase-number|task]
    Start implementation from approved tasks.
    - Resolves working phase and identifies first unchecked task
    - Primes context with related docs and research
    - Creates implementation session log

  /spec:implement-next [task]
    Implement next single task in current phase.
    - Verifies all approvals and reads spec documents
    - Primes context with documentation queries
    - Implements focused, single-task work
    - Generates conventional commit message

  /spec:implement-cleanup [context]
    Run cleanup, linting, and build validation.
    - Executes environment sanity checks
    - Runs linters and formatters
    - Verifies builds and runs iterative fixes
    - Creates git commit with all changes

-------------------
| TASK MANAGEMENT |
-------------------

  /spec:update-task <task-filter>
    Mark tasks as complete based on recent commits.
    Uses git history to identify completed work and updates task checkboxes.

  /spec:status [spec-id-or-name]
    Display all specifications and their completion status.
    Shows phase approvals, task progress, and recommended next actions.

  /spec:switch <spec-id-or-name>
    Switch active specification context.
    Resolves spec by ID or fuzzy name match.

-----------------
| COLLABORATION |
-----------------

  /spec:handoff
    Generate comprehensive handoff prompt for next agent.
    Documents progress, design decisions, known issues, and next steps.
    Useful when context window is nearing capacity.

--------------------------
| DOCUMENTATION INDEXING |
--------------------------

  /nia:index [resource-urls]
    Index documentation and repositories for AI-assisted search.
    - Creates/updates indexing jobs table
    - Indexes new sources with NIA
    - Checks status and renames completed indexes
    - Handles failed jobs with sitemap analysis

-------------
| UTILITIES |
-------------

  /summarize
    Generate concise summary of current chat session.
    Includes TLDR, key decisions, action items, and code snippets.

================================================================================
                                    NOTES
================================================================================

  - All specs are stored in .llms/spec/[ID]-[feature-name]/
  - Current active spec is tracked in .llms/spec/.current-spec
  - Approval markers are hidden files: .requirements-approved, etc.
  - Implementation logs use format: implement-[date].md
  - Documentation sources should be referenced with NIA source IDs

================================================================================