Add the complete TUI (Terminal User Interface) specification section to
docs/specification.md, covering architecture, layout, navigation, persona
system, reference picker, slash commands, shell mode, session management,
and keyboard shortcuts. The section includes 18 HTML-styled ASCII mockup
diagrams using the Dracula color palette that render with actual colors
in MkDocs.
Key specification areas:
- MainScreen layout with right-side collapsible sidebar (3 states:
hidden, visible, fullscreen cycled by shift+tab)
- Direct-to-chat launch with first-run actor selection overlay
- Persona system bundling actor + arguments + project/plan scope,
cycled with tab; argument presets cycled with ctrl+tab
- @ reference picker with fuzzy search for projects/plans/resources
- / slash commands mirroring CLI noun:verb patterns (session:new,
plan:list, project:show, actor:switch, etc.)
- ! shell mode for direct command execution
- Multi-session tabs with independent personas and conversations
- Escape-cascading navigation back to main screen
- Plan detail view with decision tree navigation
- Project detail view with resource DAG
- Permission approval workflow with diff view
- Complete keyboard shortcut reference table
New ADR files:
- ADR-044: TUI Architecture and Framework (Textual >= 1.0)
- ADR-045: TUI Persona System
- ADR-046: TUI Reference and Command System (CLI-aligned commands)
Also adds TUI mockup CSS classes to docs/stylesheets/extra.css for
Dracula-palette diagram rendering (.tui-primary, .tui-secondary,
.tui-success, .tui-warning, .tui-error, .tui-dim, .tui-bold,
.tui-bold-primary, .tui-bold-warning, .tui-primary-u, .tui-rainbow).
Created ADR-042 (Resource Type Inheritance) defining single-inheritance
`inherits` field on resource type definitions with field resolution,
collection merging, handler inheritance, polymorphic tool binding,
auto-discovery, and DAG query matching. Max depth 5, single inheritance.
Created ADR-043 (Devcontainer Integration) defining devcontainer-instance
as a subtype of container-instance with lazy activation lifecycle,
devcontainer.json parsing, three container-project association patterns
(auto-detect, explicit mount, clone-into), and execution environment
routing with a 6-level precedence chain.
Specification updates across 20+ sections:
- Glossary: Resource Type Inheritance, Devcontainer, Execution Environment
- Resource type YAML schema: `inherits` field with structure reference
- Handler, sandbox strategy, and coherence tables: devcontainer-instance
- Auto-discovery: devcontainer detection subsection with WBS diagram
- Tool capability metadata: structured environment subfields
- Technology stack: devcontainer CLI row
- Project model: execution environment subsection with YAML example
- CLI agents resource add: --mount, --clone-into flags + 4 new examples
- CLI agents plan use: --execution-environment, --execution-env-priority
- CLI agents project context set: same execution environment flags
- Command synopsis block: updated for all new flags
- Execution environment routing section with precedence table + algorithm
- Resource type YAML Example 6: Devcontainer Instance (inherited type)
- End-to-end Example 16: Devcontainer-Driven Development
- End-to-end Example 17: Explicit Container with Directory Mount
- End-to-end Example 18: Container with Remote Repo Clone
Also fixed ADR index: added missing ADR-036 through ADR-040 entries,
updated next ADR number to 044.
CONTRIBUTING.md fixes backported from sister project:
- Fixed State label capitalization (State/In Progress -> State/In progress,
State/In Review -> State/In review) to match label definitions.
- Subtasks section: changed from optional to required, with exception
clause for trivially simple issues.
- Parent links: updated to use Forgejo dependency system instead of
textual references in issue descriptions.
- Fixed nox session flag typos: nox -e -> nox -s (7 occurrences).
- Replaced "Epics and Legendaries" section with comprehensive "Ticket
Type Hierarchy" defining the three-tier hierarchy (Issue -> Epic ->
Legendary) with formal criteria tables, cross-cutting rules for
hierarchy enforcement, completion semantics, promotion/demotion, and
milestone relationship rules.
- Fixed broken internal links referencing old "Epics and Legendaries"
anchor to use "Ticket Type Hierarchy" (3 occurrences).
- Traceability example: replaced project-specific code reference with
generic example.
- Removed stray horizontal rule before Project-Specific Guidelines.
ISSUES CLOSED: #491
Add SafetyProfile as a first-class concept in the specification, composed
within AutomationProfile via a 'safety' field. This eliminates the
dual-authority problem where both AutomationProfile and a separate
SafetyProfile defined the same three safety booleans (require_sandbox,
require_checkpoints, allow_unsafe_tools) with no spec-defined resolution.
Changes:
- specification.md: Add Safety Profile glossary entry, split Automatable
Tasks into thresholds + Safety Profile sub-section, update built-in
profile matrix with safety.* prefix, update YAML examples
- ADR-041 (new): Document composition decision, field schema, relationship
to Guards, constraints, consequences, rejected alternatives (inheritance,
mixin, flat)
- ADR-017: Update profile fields table, built-in profiles, constraints,
risks, and cross-reference to ADR-041
- reference/automation_profiles.md: Rename Safety Fields to Safety Profile
sub-section, expand built-in matrix, update YAML examples
- schema/automation_profile.schema.yaml: Nest safety fields under safety
object with all SafetyProfile fields
- adr/index.md: Add ADR-041 to Tier 3 inventory
Resolves spec gap identified in issue #332.
freemo
Jeffrey Phillips Freeman