Reorganize: Move agent instructions to .instructions/ folder

To reduce clutter in the repository root and keep all agent-related
instruction files in one location:

Changes:
- Moved docs/agents/playbooks/ → .instructions/playbooks/
- Moved docs/agents/contracts/ → .instructions/contracts/
- Moved scripts/ → .instructions/scripts/
- Moved templates to .instructions/templates/
- Kept workflows in .github/workflows/ (GitHub requirement)
- Updated all path references in AGENTS.md, playbooks, scripts
- Updated example tasks and reports with new paths

Structure now:
├── AGENTS.md                    (root configuration)
├── .instructions/               (all agent instruction files)
│   ├── playbooks/              (task-specific guides)
│   ├── contracts/              (validation schemas)
│   ├── scripts/                (automation tools)
│   └── templates/              (PR/issue templates)
├── .github/workflows/          (CI/CD workflows)
└── .agent/                     (task tracking)

This keeps the root clean while maintaining full functionality.

Author: joshuahamsa

.agent/reports/BUG-003.report.yaml

@@ -17,12 +17,12 @@ changes_made:
   - Added None check before len(summary)
   - Fixed Optional type handling
 files_modified:
-  - path: scripts/validate_agent_report.py
+  - path: .instructions/scripts/validate_agent_report.py
     description: Fixed type errors
 verification:
   commands_run:
-    - mypy scripts/validate_agent_report.py
-    - python scripts/validate_agent_report.py .agent/reports/
+    - mypy .instructions/scripts/validate_agent_report.py
+    - python .instructions/scripts/validate_agent_report.py .agent/reports/
   results:
     - No type errors
     - Validation works correctly

.agent/reports/T001.report.yaml

@@ -7,7 +7,7 @@ summary:
 acceptance_criteria_results:
   - criterion: All required directories exist
     passed: true
-    evidence: ls -la shows src/, tests/, scripts/, docs/
+    evidence: ls -la shows src/, tests/, .instructions/, .agent/
   - criterion: Contract files are valid YAML
     passed: true
     evidence: yamllint passed on all contract files
@@ -23,12 +23,12 @@ files_modified:
     description: Application source directory
   - path: tests/
     description: Test directory
-  - path: docs/agents/contracts/
+  - path: .instructions/contracts/
     description: Contract definitions
 verification:
   commands_run:
     - find . -type d -name src
-    - python -c "import yaml; yaml.safe_load(open('docs/agents/contracts/task.contract.yaml'))"
+    - python -c "import yaml; yaml.safe_load(open('.instructions/contracts/task.contract.yaml'))"
   results:
     - Directories exist
     - YAML parses successfully

.agent/reports/T002.report.yaml

@@ -19,16 +19,16 @@ changes_made:
   - Added type hints
   - Implemented error handling
 files_modified:
-  - path: scripts/validate_agent_task.py
+  - path: .instructions/scripts/validate_agent_task.py
     description: Task validation script
-  - path: scripts/validate_agent_report.py
+  - path: .instructions/scripts/validate_agent_report.py
     description: Report validation script
-  - path: scripts/validate_agent_linkage.py
+  - path: .instructions/scripts/validate_agent_linkage.py
     description: Linkage validation script
 verification:
   commands_run:
-    - python scripts/validate_agent_task.py --help
-    - python scripts/validate_agent_report.py --help
+    - python .instructions/scripts/validate_agent_task.py --help
+    - python .instructions/scripts/validate_agent_report.py --help
   results:
     - Scripts execute without errors
     - Help text displayed

.agent/tasks/BUG-003.yaml

@@ -5,7 +5,7 @@ context: |
   The validate_agent_report.py script has type errors
   related to Optional types and len() calls.
 inputs:
-  - scripts/validate_agent_report.py
+  - .instructions/scripts/validate_agent_report.py
   - Type checker output
 outputs:
   - Fixed type errors
@@ -14,6 +14,6 @@ acceptance_criteria:
   - Script functionality preserved
   - Tests pass
 routing:
-  playbook: docs/agents/playbooks/debugging.md
+  playbook: .instructions/playbooks/debugging.md
   contracts:
-    - docs/agents/contracts/validation.contract.yaml
+    - .instructions/contracts/validation.contract.yaml

.agent/tasks/T001.yaml

@@ -16,6 +16,6 @@ acceptance_criteria:
   - Contract files are valid YAML
   - Scripts can be executed
 routing:
-  playbook: docs/agents/playbooks/_template.md
+  playbook: .instructions/playbooks/_template.md
   contracts:
-    - docs/agents/contracts/task.contract.yaml
+    - .instructions/contracts/task.contract.yaml

.agent/tasks/T002.yaml

@@ -16,8 +16,8 @@ acceptance_criteria:
   - Scripts check required fields
   - Scripts return proper exit codes
 routing:
-  playbook: docs/agents/playbooks/python.md
+  playbook: .instructions/playbooks/python.md
   contracts:
-    - docs/agents/contracts/task.contract.yaml
-    - docs/agents/contracts/report.contract.yaml
-    - docs/agents/contracts/validation.contract.yaml
+    - .instructions/contracts/task.contract.yaml
+    - .instructions/contracts/report.contract.yaml
+    - .instructions/contracts/validation.contract.yaml

.github/workflows/post-task-integration.yml

@@ -57,7 +57,7 @@ jobs:
           GITHUB_REPOSITORY: ${{ github.repository }}
         run: |
           echo "Running integration for task: ${{ steps.detect.outputs.task_id }}"
-          python scripts/github_integrator.py ${{ steps.detect.outputs.task_id }} --ci-mode
+          python .instructions/scripts/github_integrator.py ${{ steps.detect.outputs.task_id }} --ci-mode
           
       - name: Validate Ledger Updated
         if: steps.detect.outputs.task_id != ''

.github/workflows/validate-agent-artifacts.yml

@@ -3,10 +3,10 @@ name: Validate Agent Artifacts
 on:
   pull_request:
     paths:
-      - "docs/agents/contracts/**/*.yaml"
+      - ".instructions/contracts/**/*.yaml"
       - ".agent/**/*.yaml"
-      - "scripts/validate_agent_*.py"
-      - ".github/workflows/validate-agent-artifacts.yml"
+      - ".instructions/scripts/validate_agent_*.py"
+      - ".instructions/workflows/validate-agent-artifacts.yml"
 
 permissions:
   contents: read
@@ -28,4 +28,4 @@ jobs:
 
       - name: Validate reports
         run: |
-          python scripts/validate_agent_report.py .agent/reports/
+          python .instructions/scripts/validate_agent_report.py .agent/reports/

.github/workflows/validate-agents.yaml

@@ -25,19 +25,19 @@ jobs:
       - name: Validate task contracts
         run: |
           if [ -d ".agent/tasks" ]; then
-            python scripts/validate_agent_task.py .agent/tasks/
+            python .instructions/scripts/validate_agent_task.py .agent/tasks/
           else
             echo "No tasks directory found, skipping task validation"
           fi
 
       - name: Validate report contracts
         run: |
           if [ -d ".agent/reports" ]; then
-            python scripts/validate_agent_report.py .agent/reports/
+            python .instructions/scripts/validate_agent_report.py .agent/reports/
           else
             echo "No reports directory found, skipping report validation"
           fi
 
       - name: Validate task/report linkage
         run: |
-          python scripts/validate_agent_linkage.py
+          python .instructions/scripts/validate_agent_linkage.py