🧩 REQUIREMENTS ANALYSIS

Elicit and document functional and non-functional requirements for the terminal-based assistant.

---

👥 STAKEHOLDERS

Role	Needs
End User (Developer)	Simple, predictable CLI. Can pipe, redirect, chain prompts. Can suppress parts of output. Can attach context files.
Maintainer	Modular, readable, testable code. Easy to extend models or add -o options.
System Integrator	Must work in CI/CD pipelines, headless environments. Logs must be machine-parseable.
Security Auditor	Must not leak secrets. Must validate paths. Must allow env sourcing.

---

📋 FUNCTIONAL REQUIREMENTS (FR)

Required system behaviour.

ID	Requirement	Notes
FR-01	Accept prompt via CLI args or stdin	✔ Implemented
FR-02	Accept input file attachment via --input-file	✔ Implemented
FR-03	Allow output directory override via --output-dir	✔ Implemented
FR-04	Allow output filename override via --output-file	✔ Implemented
FR-05	Support dry-run mode (--dry-run)	✔ Implemented
FR-06	Support verbose mode (--verbose)	✔ Implemented
FR-07	Generate unique, hierarchical message IDs (speech_id-parent_id)	✔ Implemented via GenMessageId
FR-08	Log metadata in structured format: [timestamp, speaker, message_id]	✔ Implemented
FR-09	Output model response to stdout by default	✔ Implemented
FR-10	Append conversation to log file in Markdown/CommonMark	✔ Implemented
FR-11	Support model override via --model or TAI_MODEL	✔ Implemented
FR-12	Extract and log token usage + model + conversation ID	✔ Implemented via ExtractMetadata
FR-13	Validate --output-dir exists before writing	✔ Implemented
FR-14	Source env vars from file via --env-file	✔ Implemented
FR-15	Support -o flag for output control (e.g., NO_USER_STDOUT, NO_AI_FILE, etc.)	❌ Pending
FR-16	Support --parent-id to thread conversations	❌ Pending
FR-17	Support DeepSeek API routing	❌ Pending
FR-18	Support new “response API” (TBD spec)	❌ Placeholder
FR-19	Allow composable/chunked operations (e.g., cache, state)	❌ Architecture note

---

⚙️ NON-FUNCTIONAL REQUIREMENTS (NFR)

Quality attributes, constraints, performance targets.

ID	Requirement	Priority
NFR-01	Must be POSIX shell compatible (no bashisms)	High
NFR-02	Must not depend on external tools beyond curl, jq, date, sha256sum	High
NFR-03	Must handle large prompts (>10 kB) gracefully	Medium
NFR-04	Must log in append-only mode to avoid corruption	High
NFR-05	Must sanitize paths to prevent directory traversal	High
NFR-06	Must allow suppression of any output component via -o	High
NFR-07	Must support message threading for context chaining	High
NFR-08	Must be extensible for future models (Claude, Mistral, local LLMs)	Medium
NFR-09	Must be testable via shell scripts or bats-core	Medium
NFR-10	Must output parseable logs for external tools (e.g., grep '^\[.*\]')	High

---

🚫 ASSUMPTIONS & CONSTRAINTS

Type	Description
Assumption	OPENAI_API_KEY and OPENAI_PROJECT_ID are set or provided via --env-file.
Assumption	jq, curl, sha256sum are available in PATH.
Constraint	Output format must preserve ^\[[^\]]+\] regex compatibility for log extraction.
Constraint	Backward compatibility with existing log consumers must not be broken.
Constraint	The program must not auto-create arbitrary directories—only $LOG_STORAGE_PATH by default.

---

🏗️ STEP 3: WORK BREAKDOWN STRUCTURE (WBS)

Break the project into deliverables and tasks.

---

🔶 LEVEL 1: MAJOR DELIVERABLES

1. Core CLI Engine
2. Output Control System (-o flag)
3. Conversation Threading (--parent-id)
4. Multi-Model Support (DeepSeek + Response API)
5. Logging & Metadata System
6. Testing & Validation Suite
7. Documentation & Examples

---

🔷 LEVEL 2: SUB-DELIVERABLES & TASKS

1. Core CLI Engine

• Parse CLI args (--output-dir, --model, etc.)
• Read prompt from args or stdin
• Read attachment file
• Validate output directory
• Dry-run and verbose modes
• Add -o flag parser and dispatcher

2. Output Control System (-o)

Implement -o "NO_USER_FILE,NO_AI_STDOUT,METADATA_ONLY" etc.

• Design output-control grammar (comma-separated flags)
• Map flags to suppression logic in Record() and Speak()
• Modify Record() to conditionally write to file
• Modify Speak() to conditionally echo to stdout
• Add unit tests for each -o combination

3. Conversation Threading (--parent-id)

Allow each message to reference an existing parent ID.

• Add --parent-id=<MESSAGE_ID> CLI arg
• Modify GenMessageId to accept explicit parent ID
• Store parent ID in metadata
• Add context directory logic: auto-load .ctx.d/ files if --output-dir is set
• Support --no-dispatch to stage request without sending (for multi-agent scenarios)

4. Multi-Model Support

Support DeepSeek and future “Response API”.

• Detect models with prefix deepseek-
• Route to https://api.deepseek.com/v1/chat/completions
• Adjust request body format for DeepSeek, if required
• Add --response-api flag to use the new endpoint
• Abstract API call into CallModel(model, messages)

5. Logging & Metadata System

• Generate message IDs
• Log in [timestamp, speaker, id] format
• Append indented speech with --- separator
• Add option to omit metadata from stdout/file via -o
• Add option to strip whitespace prefix for clean extraction (sed compatible)

6. Testing & Validation

• Write test: dry-run outputs placeholder
• Write test: invalid --output-dir exits with error
• Write test: -o NO_AI_STDOUT suppresses model output to terminal
• Write test: --parent-id generates correct child ID
• Write test: DeepSeek model routes to correct endpoint

7. Documentation & Examples

• Update --help with -o and --parent-id usage
• Add example: context chaining with .ctx.d/
• Add example: suppressing output components
• Add example: multi-model usage
• Add VIM integration example (already in header)

---

🗂️ WBS TREE (text representation)

terminal-ai v1.0
├── 1. Core CLI Engine
│   ├── 1.1 Parse CLI args
│   ├── 1.2 Read prompt (args/stdin)
│   ├── 1.3 Read attachment file
│   ├── 1.4 Validate output dir
│   ├── 1.5 Dry-run / verbose
│   └── 1.6 Implement -o flag parser
├── 2. Output Control (-o)
│   ├── 2.1 Define suppression grammar
│   ├── 2.2 Integrate with Record()
│   ├── 2.3 Integrate with Speak()
│   └── 2.4 Unit tests for -o
├── 3. Conversation Threading
│   ├── 3.1 Add --parent-id arg
│   ├── 3.2 Modify GenMessageId
│   ├── 3.3 Context directory auto-load
│   └── 3.4 --no-dispatch staging
├── 4. Multi-Model Support
│   ├── 4.1 Detect DeepSeek models
│   ├── 4.2 Route to DeepSeek API
│   ├── 4.3 Support Response API
│   └── 4.4 Abstract CallModel()
├── 5. Logging & Metadata
│   ├── 5.1 Preserve log format
│   ├── 5.2 Add -o metadata suppression
│   └── 5.3 Support whitespace-stripping extraction
├── 6. Testing Suite
│   ├── 6.1 Dry-run test
│   ├── 6.2 Invalid path test
│   ├── 6.3 -o suppression test
│   ├── 6.4 Parent-ID test
│   └── 6.5 DeepSeek routing test
└── 7. Documentation
   ├── 7.1 Update --help
   ├── 7.2 Context chaining example
   ├── 7.3 Output suppression example
   ├── 7.4 Multi-model example
   └── 7.5 VIM integration example

---

🚀 CHECKLIST

✅ Clear project scope
✅ Complete functional and non-functional requirements
✅ Detailed WBS with associated tasks

---