Add document on AI assisted development

.gitignore

@@ -75,3 +75,6 @@ screens
 
 .test.yaml
 .nicegui
+
+# Claude Code / GSD tooling
+.claude/

.planning/PROJECT.md

@@ -0,0 +1,62 @@
+# AI Agents in CATio — Executive Summary Document
+
+## What This Is
+
+A documentation page for the CATio Sphinx docs (in `docs/explanations/`) that provides an executive summary of how AI agents (Claude Opus) were used to deliver a major architectural overhaul of the CATio project in approximately two weeks. Targeted at management and stakeholders, making the case for AI-assisted development.
+
+## Core Value
+
+Demonstrate through concrete evidence that AI-assisted development enabled a single developer to deliver architectural changes of a scale and quality that would typically require a larger team or significantly more time.
+
+## Requirements
+
+### Validated
+
+(None yet — ship to validate)
+
+### Active
+
+- [ ] High-level overview of the architectural changes (YAML-driven dynamic controllers replacing hard-coded Python classes, catio-terminals GUI)
+- [ ] Quantified scale of changes (113 commits, ~23k lines new source, 16 to 56 source files, 29 terminal types in YAML)
+- [ ] Analysis of where Claude was used to achieve rapid development (code generation, refactoring, module decomposition)
+- [ ] Before/after comparison showing architecture and maintainability improvements
+- [ ] Acknowledgement that this work predates agent skills and structured workflows
+- [ ] Reference to builder2ibek as an example of more mature AI agent usage with proper agent features
+- [ ] Advocacy tone — making the case for AI-assisted development based on this experience
+- [ ] Follows existing Sphinx/MyST markdown format used by other explanation pages
+
+### Out of Scope
+
+- Test infrastructure and simulator changes — focus on architecture only
+- Documentation commits and cleanup — focus on the code architecture
+- Step-by-step tutorial on using AI agents — this is an executive summary
+- Detailed code examples — keep it high-level for stakeholder audience
+
+## Context
+
+- The CATio project controls EtherCAT I/O devices via Beckhoff TwinCAT
+- Before commit df5c3c4, terminal handling required explicit Python classes (~1200 lines in catio_hardware.py per terminal family)
+- After the changes: terminal types are defined in YAML (14,276 lines covering 29 terminal types), generated from vendor Beckhoff XML, and editable via a NiceGUI web application
+- Dynamic controller generation creates FastCS controller classes at runtime from YAML definitions
+- The entire body of work was done by Giles Knap over ~2 weeks using Claude Opus
+- 100 commits by Giles, 11 by copilot-swe-agent for doc updates, 2 by Gregory Gay
+- The work predates use of GSD workflows, agent skills, and other structured AI development features
+- builder2ibek (sibling project) is a migration tool built with more mature AI agent features and serves as a better example of the full agent workflow
+
+## Constraints
+
+- **Format**: Must be a Sphinx/MyST markdown page in `docs/explanations/`
+- **Audience**: Management and stakeholders, not developers
+- **Tone**: Advocacy — make the case based on evidence
+- **Length**: Executive summary — concise, not exhaustive
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Architecture focus only | Stakeholders care about what changed and why, not test/doc commits | — Pending |
+| Advocacy tone | User wants to make the case for AI-assisted development | — Pending |
+| Reference builder2ibek | Shows trajectory of improvement in AI agent usage | — Pending |
+
+---
+*Last updated: 2026-03-02 after initialization*

.planning/REQUIREMENTS.md

@@ -0,0 +1,68 @@
+# Requirements: AI Agents Executive Summary
+
+**Defined:** 2026-03-02
+**Core Value:** Demonstrate through concrete evidence that AI-assisted development delivered a major architectural overhaul rapidly and with high quality
+
+## v1 Requirements
+
+### Content
+
+- [ ] **CONT-01**: Document includes a concise before-state description (hard-coded Python classes per terminal type)
+- [ ] **CONT-02**: Document includes quantified scale metrics from git history (commits, lines, files, terminal types)
+- [ ] **CONT-03**: Document includes high-level overview of the architectural transformation (YAML-driven dynamic controllers, catio-terminals GUI)
+- [ ] **CONT-04**: Document identifies where Claude Opus was used to achieve rapid development
+- [ ] **CONT-05**: Document states the timeline (~2 weeks, single developer)
+- [ ] **CONT-06**: Document frames the developer as the agent who directed AI, not AI as autonomous hero
+
+### Advocacy
+
+- [ ] **ADVC-01**: Document includes trajectory arc — this work predates agent skills, builder2ibek shows maturation
+- [ ] **ADVC-02**: Document highlights maintainability improvement (new terminal = edit YAML, not write Python)
+
+### Format
+
+- [ ] **FRMT-01**: Document is a Sphinx/MyST markdown page in docs/explanations/
+- [ ] **FRMT-02**: Document is registered in docs/explanations.md toctree
+- [ ] **FRMT-03**: Document is short and scannable — executive summary, not a report
+
+## v2 Requirements
+
+### Content
+
+- **CONT-07**: Before/after architecture diagram (mermaid)
+- **CONT-08**: Quality evidence (test coverage, validation against Beckhoff XML)
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| Step-by-step AI tutorial | Wrong audience — stakeholders, not developers |
+| Detailed code examples | Executive summary, not technical reference |
+| Productivity multiplier claims | Undermines credibility — let raw numbers speak |
+| Test/doc/cleanup commit coverage | Architecture focus only per user direction |
+| Lengthy prose sections | Must be short and snappy |
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| CONT-01 | Phase 1 | Pending |
+| CONT-02 | Phase 1 | Pending |
+| CONT-03 | Phase 1 | Pending |
+| CONT-04 | Phase 1 | Pending |
+| CONT-05 | Phase 1 | Pending |
+| CONT-06 | Phase 1 | Pending |
+| ADVC-01 | Phase 1 | Pending |
+| ADVC-02 | Phase 1 | Pending |
+| FRMT-01 | Phase 2 | Pending |
+| FRMT-02 | Phase 2 | Pending |
+| FRMT-03 | Phase 2 | Pending |
+
+**Coverage:**
+- v1 requirements: 11 total
+- Mapped to phases: 11
+- Unmapped: 0
+
+---
+*Requirements defined: 2026-03-02*
+*Last updated: 2026-03-02 after roadmap creation*

.planning/ROADMAP.md

@@ -0,0 +1,56 @@
+# Roadmap: AI Agents Executive Summary
+
+## Overview
+
+Deliver a single Sphinx explanation page that makes the case for AI-assisted development using the CATio architectural transformation as evidence. Phase 1 writes the document content (evidence, narrative, advocacy). Phase 2 integrates it into the Sphinx docs build and validates format compliance.
+
+## Phases
+
+**Phase Numbering:**
+- Integer phases (1, 2, 3): Planned milestone work
+- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
+
+Decimal phases appear between their surrounding integers in numeric order.
+
+- [ ] **Phase 1: Document Content** - Draft the executive summary with all evidence, narrative, and advocacy sections
+- [ ] **Phase 2: Sphinx Integration** - Place the page in the docs tree, register in toctree, validate build
+
+## Phase Details
+
+### Phase 1: Document Content
+**Goal**: A complete draft of the executive summary exists with verified metrics, before/after narrative, honest AI framing, and advocacy arc
+**Depends on**: Nothing (first phase)
+**Requirements**: CONT-01, CONT-02, CONT-03, CONT-04, CONT-05, CONT-06, ADVC-01, ADVC-02
+**Success Criteria** (what must be TRUE):
+  1. Document contains a metrics table with verifiable numbers from git history (commits, lines, files, terminal types)
+  2. Document describes the before-state (hard-coded Python) and after-state (YAML-driven dynamic controllers) as a clear transformation arc
+  3. Document identifies specific tasks where Claude Opus was used and frames the developer as the directing agent
+  4. Document includes the trajectory arc from pre-agent CATio work to builder2ibek as evidence of maturing practice
+  5. Document reads as a concise, scannable executive summary -- not a technical report
+**Plans**: 1 plan
+
+Plans:
+- [ ] 01-01-PLAN.md -- Verify metrics, write executive summary, author review
+
+### Phase 2: Sphinx Integration
+**Goal**: The document is a first-class page in the CATio docs that builds cleanly and is discoverable in the explanations section
+**Depends on**: Phase 1
+**Requirements**: FRMT-01, FRMT-02, FRMT-03
+**Success Criteria** (what must be TRUE):
+  1. Document exists at docs/explanations/ai-assisted-development.md in valid MyST markdown
+  2. Document appears in the explanations toctree and is navigable from the docs site
+  3. `tox -e docs` passes with no warnings related to this page
+**Plans**: TBD
+
+Plans:
+- [ ] 02-01: TBD
+
+## Progress
+
+**Execution Order:**
+Phases execute in numeric order: 1 -> 2
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. Document Content | 0/1 | Planned | - |
+| 2. Sphinx Integration | 0/? | Not started | - |

.planning/STATE.md

@@ -0,0 +1,59 @@
+# Project State
+
+## Project Reference
+
+See: .planning/PROJECT.md (updated 2026-03-02)
+
+**Core value:** Demonstrate through concrete evidence that AI-assisted development delivered a major architectural overhaul rapidly and with high quality
+**Current focus:** Phase 1: Document Content
+
+## Current Position
+
+Phase: 1 of 2 (Document Content)
+Plan: 0 of ? in current phase
+Status: Ready to plan
+Last activity: 2026-03-02 -- Roadmap created
+
+Progress: [..........] 0%
+
+## Performance Metrics
+
+**Velocity:**
+- Total plans completed: 0
+- Average duration: -
+- Total execution time: 0 hours
+
+**By Phase:**
+
+| Phase | Plans | Total | Avg/Plan |
+|-------|-------|-------|----------|
+| - | - | - | - |
+
+**Recent Trend:**
+- Last 5 plans: -
+- Trend: -
+
+*Updated after each plan completion*
+
+## Accumulated Context
+
+### Decisions
+
+Decisions are logged in PROJECT.md Key Decisions table.
+Recent decisions affecting current work:
+
+- [Roadmap]: Two phases -- content drafting then Sphinx integration. Research suggested three phases but the deliverable is a single page; two natural boundaries suffice.
+
+### Pending Todos
+
+None yet.
+
+### Blockers/Concerns
+
+- Author (Giles Knap) input may be needed to confirm exact metric scoping (architecture-only vs all commits) and builder2ibek trajectory description. Research flagged this; plan-phase should account for it.
+
+## Session Continuity
+
+Last session: 2026-03-02
+Stopped at: Roadmap created, ready for Phase 1 planning
+Resume file: None

.planning/codebase/ARCHITECTURE.md

@@ -0,0 +1,80 @@
+# Architecture
+
+## Pattern
+
+**Layered controller architecture** built on FastCS framework.
+
+The system follows a hierarchical controller pattern where a top-level `CATioController` discovers EtherCAT hardware via ADS, creates sub-controllers for each device/terminal, and exposes their attributes as EPICS PVs through FastCS.
+
+## Layers
+
+```
+┌─────────────────────────────────────────────┐
+│  EPICS / NiceGUI (Presentation)             │
+│  FastCS backends: softioc, nicegui          │
+├─────────────────────────────────────────────┤
+│  FastCS Framework (Attribute Layer)         │
+│  AttrR, AttrRW, AttrW → PV mapping         │
+├─────────────────────────────────────────────┤
+│  CATio Controllers (Domain Layer)           │
+│  CATioController → Device/Terminal subs     │
+│  Hardware-specific controllers (EL3xxx etc) │
+├─────────────────────────────────────────────┤
+│  CATio Dynamic Layer                        │
+│  Dynamic CoE, Symbol, Type controllers      │
+│  YAML-driven terminal configuration         │
+├─────────────────────────────────────────────┤
+│  ADS Client (Transport Layer)               │
+│  Async TCP/UDP, AMS protocol, routing       │
+├─────────────────────────────────────────────┤
+│  TwinCAT PLC / EtherCAT Hardware            │
+└─────────────────────────────────────────────┘
+```
+
+## Key Abstractions
+
+### Controllers (`src/fastcs_catio/catio_controller.py`)
+- `CATioController` — Base controller with ADS connection management, attribute creation, notification handling
+- `CATioDeviceController` — Sub-controller for EtherCAT master devices
+- `CATioTerminalController` — Sub-controller for EtherCAT slave terminals
+
+### Hardware Controllers (`src/fastcs_catio/catio_hardware.py`)
+- Terminal-specific controllers: `EL1xxx`, `EL2xxx`, `EL3xxx`, `EL4xxx`, `EL3702` (oversampling)
+- Each defines channel counts, I/O functions, attribute mappings
+
+### Dynamic Controllers (`src/fastcs_catio/catio_dynamic_controller.py`, `catio_dynamic_coe.py`, `catio_dynamic_symbol.py`)
+- Runtime-generated controllers from YAML terminal type definitions
+- CoE (CANopen over EtherCAT) object discovery and attribute creation
+- Symbol-based dynamic attribute creation
+
+### ADS Client (`src/fastcs_catio/client.py`)
+- `CatioClient` — Full async ADS client with TCP/UDP transport
+- Connection management, route creation/deletion
+- Symbol table reading, notification subscriptions
+- Device/slave introspection
+
+### Attribute I/O (`src/fastcs_catio/catio_attribute_io.py`)
+- `CATioControllerAttributeIO` — Bridge between FastCS attributes and ADS read/write
+- Handles polling periods, notification-based updates, value caching
+
+## Data Flow
+
+1. **Startup:** CLI creates `CATioController` → connects via ADS → discovers devices/terminals
+2. **Introspection:** For each device/terminal, creates sub-controllers → reads attributes from ADS
+3. **Dynamic:** Loads YAML terminal configs → creates dynamic CoE/symbol controllers
+4. **Runtime:** FastCS runs scan loop → polls ADS for attribute updates → pushes to EPICS PVs
+5. **Notifications:** ADS notifications stream → update controller attributes → propagate to EPICS
+
+## Entry Points
+
+- `src/fastcs_catio/__main__.py` — Typer CLI app with `run` command, connects to ADS and starts FastCS
+- `src/catio_terminals/__main__.py` — NiceGUI web app for terminal configuration browsing
+- `tests/ads_sim/__main__.py` — ADS simulation server for testing
+
+## Second Package: catio-terminals
+
+Separate package in `src/catio_terminals/` providing a web-based tool for:
+- Browsing Beckhoff ESI XML terminal catalogs
+- Viewing PDO mappings, CoE objects, symbol definitions
+- Managing terminal type YAML configuration files
+- Tree-view navigation of terminal hierarchies