refactored in doc and updated poetry.lock

Author: DinisCruz

docs/guide__agent-workflow-issues-format.md

@@ -0,0 +1,165 @@
+# Agent Workflow Guide: .issues File Format
+
+**Version:** v0.1.0
+**Date:** 2026-02-13
+**Status:** Active
+
+## Overview
+
+The `.issues` flat file format enables AI agents to manage issue tracking
+directly through text files, without requiring CLI commands or API calls.
+Files live in the `.issues/` directory and are version-controlled with Git.
+
+## File Format
+
+Each `.issues` file contains one issue per line in pipe-delimited format:
+
+```
+{Type}-{Number} | {status} | {description}
+```
+
+### Examples
+
+```
+Task-1 | todo | Enable CloudFront logging
+Bug-3 | confirmed | Login page returns 500 on empty email
+Workstream-1 | in-progress | Observability improvements
+```
+
+### Hierarchy (tab-indented children)
+
+```
+Workstream-1 | in-progress | Observability
+	Task-1 | todo | CloudFront logs
+	Task-2 | done | S3 logging
+	Task-3 | todo | Dashboards
+```
+
+Parent nodes automatically get `has-task` links to their children.
+
+### Cross-References
+
+```
+Task-1 | todo | Fix login -> Bug-3
+```
+
+The `->` syntax creates a `relates-to` link from Task-1 to Bug-3.
+
+### Comments
+
+Lines starting with `#` are comments:
+
+```
+# Sprint 4 tasks
+Task-1 | todo | API endpoints
+```
+
+## Label Format
+
+Labels follow the pattern `{Type}-{Number}`:
+
+| Pattern | Type | Example |
+|---------|------|---------|
+| `Task-N` | task | Task-1, Task-42 |
+| `Bug-N` | bug | Bug-1, Bug-99 |
+| `Workstream-N` | workstream | Workstream-1 |
+| `Feature-N` | feature | Feature-3 |
+| `Question-N` | question | Question-1 |
+| `Risk-N` | risk | Risk-5 |
+| `User-Journey-N` | user-journey | User-Journey-1 |
+
+The type is inferred from the label prefix (everything before the final `-N`).
+
+## Valid Statuses by Type
+
+| Type | Valid Statuses |
+|------|---------------|
+| task | backlog, todo, in-progress, review, done |
+| bug | backlog, confirmed, in-progress, testing, resolved, closed |
+| workstream | todo, in-progress, done, blocked |
+| feature | proposed, approved, in-progress, released |
+| question | open, answered, closed |
+| risk | identified, mitigated, accepted, closed |
+| user-journey | draft, in-progress, done |
+
+## Agent Workflow
+
+### 1. Creating a Workstream
+
+Create a new `.issues` file in `.issues/`:
+
+```
+# .issues/workstream-auth.issues
+Workstream-1 | todo | Implement authentication
+	Task-1 | todo | Add login endpoint
+	Task-2 | todo | Add token validation
+	Task-3 | todo | Add logout endpoint
+```
+
+### 2. Updating Progress
+
+Edit the file to change statuses as work progresses:
+
+```
+Workstream-1 | in-progress | Implement authentication
+	Task-1 | done | Add login endpoint
+	Task-2 | in-progress | Add token validation
+	Task-3 | todo | Add logout endpoint
+```
+
+### 3. Tracking Bugs
+
+Create a separate bugs file or add to existing files:
+
+```
+# .issues/bugs-auth.issues
+Bug-1 | confirmed | Token refresh fails silently
+Bug-2 | resolved | Login returns 500 on empty password
+```
+
+### 4. Validating Files
+
+Use the check service to validate files:
+
+```bash
+issues-fs check                      # check all .issues files
+issues-fs check auth.issues          # check specific file
+```
+
+### 5. Exporting to JSON
+
+Use normalise to export to the JSON issue structure:
+
+```bash
+issues-fs normalise --dry-run        # preview what would be written
+issues-fs normalise                  # write JSON files
+```
+
+### 6. Schema Validation
+
+The schema service validates statuses against predefined type schemas.
+Unknown types are flagged but not treated as errors.
+
+## File Organisation
+
+Recommended structure for the `.issues/` directory:
+
+```
+.issues/
+├── workstream-feature-a.issues     # workstream with child tasks
+├── workstream-feature-b.issues     # another workstream
+├── bugs-sprint-4.issues            # bugs from current sprint
+├── questions.issues                # open questions/decisions
+└── guide__agent-workflow.md        # this guide
+```
+
+## Integration with Graph__Repository
+
+The `Graph__Repository` automatically discovers and loads `.issues` files:
+
+- `nodes_list_all()` includes nodes from `.issues` files
+- JSON `issue.json` files take precedence over `.issues`-sourced nodes
+- Cache is invalidated when `.issues` files change
+
+This means `.issues` files and JSON files coexist. The `.issues` format
+is the lightweight authoring format; JSON is the canonical storage.