Skip to content

WORKFLOWS.md

Latest commit

 

History

History
253 lines (169 loc) · 8.8 KB

WORKFLOWS.md

File metadata and controls

253 lines (169 loc) · 8.8 KB

DevTrail - Recommended Workflows

Patterns and cadences for using DevTrail day to day.

Strange Days Tech

Languages: English | Español | 简体中文

Table of Contents

  1. After Initial Setup
  2. Daily Development
  3. Keeping DevTrail Updated
  4. Checking Project Health
  5. Using Skills (Active Documentation)
  6. Team Patterns
  7. Understanding Versions

After Initial Setup

You ran devtrail init . and committed the result. Now what?

  1. Open your project with your AI coding assistant (Claude Code, Cursor, Gemini CLI, etc.)
  2. The assistant will automatically read the DevTrail directives (CLAUDE.md, GEMINI.md, etc.)
  3. From this point on, the assistant creates documentation in .devtrail/ as part of its normal workflow
  4. No extra configuration needed — DevTrail works passively through the directive files

Daily Development

The Passive Loop

  1. Work normally with your AI assistant — write features, fix bugs, refactor
  2. The AI creates documents in .devtrail/ according to the governance rules:
    • AILOG for significant implementations (>10 lines changed)
    • AIDEC when choosing between alternatives
    • ADR for architectural decisions
    • ETH when ethical concerns arise
  3. Review documents flagged with review_required: true
  4. Commit documentation together with the corresponding code changes

When to Create Documents Manually

Use the active system (skills) when:

  • The AI missed documenting a significant change
  • You (a human) made a decision that should be recorded
  • You want to create a REQ, TES, TDE, or INC document
  • You want to check documentation compliance

Keeping DevTrail Updated

Recommended Cadence

  • Monthly or when you see a new release on GitHub
  • Check the releases page for changelogs

Update Commands

Goal Command
Update both framework and CLI devtrail update
Update only templates and governance files devtrail update-framework
Update only the CLI binary devtrail update-cli

Framework and CLI have independent versions — you can update one without the other. See Understanding Versions.

After Updating

  1. Review changes to directive files and governance docs
  2. Commit the updated files: git add .devtrail/ && git commit -m "chore: update DevTrail framework"
  3. If you customized any framework files, check for conflicts

Checking Project Health

CLI Status

devtrail status

Shows: framework version, CLI version, directory structure integrity, and document statistics by type. Use it to verify that the installation is healthy.

Documentation Compliance (Skill)

/devtrail-status

The /devtrail-status skill (available in Claude Code and Gemini CLI) analyzes:

  • Which recent code changes lack corresponding documentation
  • Document compliance against governance rules
  • Overall documentation health

Using Skills (Active Documentation)

DevTrail has two documentation systems:

System How it works When to use
Passive AI auto-documents via directive files Default — happens automatically
Active User invokes skills to create docs When passive missed something, or for human decisions

Available Skills

Skill Purpose
/devtrail-status Check documentation compliance
/devtrail-new Create any document type (suggests best fit)
/devtrail-ailog Quick AILOG creation
/devtrail-aidec Quick AIDEC creation
/devtrail-adr Quick ADR creation

For full skill details, see the README.

Team Patterns

PR Reviews

  • Check that significant code changes include corresponding .devtrail/ documents
  • Review any documents with review_required: true
  • Verify that AILOGs accurately describe what the AI did

Onboarding New Team Members

  1. Point them to .devtrail/QUICK-REFERENCE.md for a quick overview
  2. Have them read recent ADRs to understand architectural context
  3. Show them AILOGs from recent features to see how documentation works in practice

Sprint Retrospectives

  • Review AILOGs and AIDECs from the sprint to understand AI contribution patterns
  • Identify undocumented decisions that should have been recorded
  • Check TDE documents for accumulating technical debt

Shared AI Assistant Usage

When multiple team members use AI assistants on the same project:

  • Each assistant session produces its own documents
  • The agent field in metadata identifies which assistant created each document
  • Review overlapping or contradictory AIDECs during PR review

China Regulatory Workflow (opt-in)

If your project operates in mainland China or processes personal information of mainland China users, enable the China scope and follow this workflow.

One-time Setup

  1. Edit .devtrail/config.yml and add china to regional_scope: 
    regional_scope:
  - global
  - eu      # if also EU-subject
  - china
  2. Run devtrail compliance --region china to see the baseline (all checks will fail until you create the supporting documents).
  3. Read the guides installed under .devtrail/00-governance/:
    • CHINA-REGULATORY-FRAMEWORK.md — overview and coverage matrix
    • TC260-IMPLEMENTATION-GUIDE.md — five-level risk grading
    • PIPL-PIPIA-GUIDE.md — when a PIPIA is required and what it must contain
    • CAC-FILING-GUIDE.md — single vs dual filing, status lifecycle
    • GB-45438-LABELING-GUIDE.md — explicit + implicit labeling design

When You Add a Generative AI Model

Bundle of documents to create together (cross-linked via related:):

Document Purpose Required when
MCARD Model card with cac_filing_required, gb45438_applicable, tc260_risk_level Always for in-scope models
TC260RA Risk grading (scenario × intelligence × scale → 5 levels) Always
AILABEL Explicit + implicit labeling per GB 45438 When the model generates content
CACFILE Algorithm filing record When cac_filing_required: true
PIPIA Personal-info impact assessment (Art. 55-56) When personal info is processed
SBOM Training-data inventory + GB/T 45652 compliance Always

devtrail compliance --region china confirms the bundle is complete.

When an Incident Occurs

The INC template includes a CSL 2026 Incident Reporting section. Set:

csl_severity_level: relatively_major   # or particularly_serious | major | general
csl_report_deadline_hours: 4           # 1 for particularly_serious, 4 for relatively_major

devtrail validate enforces severity-to-deadline coherence (CROSS-008, CROSS-009). Major+ incidents must be closed (status accepted) within 30 days for the CSL-003 check to pass.

Cross-Border Data Transfer

When a process involves transferring personal information out of mainland China, set pipl_cross_border_transfer: true on the PIPIA and document the chosen mechanism (CAC security assessment / certification / standard contract) in the Cross-Border Transfer Analysis section. CROSS-011 will warn if none is documented.

Daily Compliance Check

# Before merging a feature branch that touches AI services
devtrail validate                    # cross-rules including CROSS-004..011
devtrail compliance --region china   # per-framework score

Understanding Versions

DevTrail uses independent versioning for its two components:

Component Tag prefix Contains Updated via
Framework fw- Templates, governance docs, directives, scripts devtrail update-framework
CLI cli- The devtrail binary devtrail update-cli

Why Independent Versions?

  • Framework changes (new templates, updated rules) are more frequent
  • CLI changes (new commands, bug fixes) follow a different cadence
  • You can update governance docs without needing a new CLI binary

Checking Your Versions

devtrail about     # Quick version check
devtrail status    # Full health report including versions

For detailed CLI information, see the CLI Reference.

DevTrail — Because every change tells a story.

Back to docs • README • Strange Days Tech