dev-support

Dev Support Skill

This skill helps manage development projects across multiple work sessions that may be interrupted in a short time. It emphasizes documentation-driven development and context retention to minimize productivity loss from switching between tasks.

Core Principles

Two-Layer Documentation Structure: Project level (docs/) + Feature Level (docs/dev/[feature-name]/)
Highest-Priority File: CONTEXT.md is the most important file for interruption and resumption
Technology Stack Agnostic: Works with any programming language or framework
Flexible Sessions: Always ask the user for the session duration (default: 30 minutes)
Manual First: Use standard commands unless the user explicitly requests helper scripts
Architectural Consistency: Ensure that new features are consistent with the project's architecture
AI double-check: Before user confirmation, have another AI tool available in the environment (GitHub Copilot CLI, Gemini CLI, Claude Code, etc.) perform a review

Session Start Workflow

Confirm Session Duration: "How long is this session? (Default: 30 minutes)"
Check the Project's Documentation Structure:
- docs/README.md (documentation index)
- ARCHITECTURE.md (project-level architecture)
- docs/dev/README.md (list of in-progress features)
docs/dev/**/ within CONTEXT.md find and read the file
Summarize the Previous Session:
- Date/time and duration
- The task being worked on
- Completed items and incomplete items
- CONTEXT.md next actions from
ROADMAP.md if it exists, display the overall progress
Confirm with the User: "Would you like to resume from where you left off?"
Handling Existing Projects: If structured documentation does not exist, propose a documentation setup for the entire project

New Feature Development

Verify Consistency with the Project Architecture:
- ARCHITECTURE.md or docs/architecture/overview.md load
- Verify whether the feature fits the existing system design
- Identify affected components
Notify the user: docs/dev/[feature-name]/ Recommend creating the directory
Creation proposal:
- SPEC.md: Requirements, user stories, acceptance criteria
- DESIGN.md: Architecture, technical decisions, API design
- TEST_PLAN.md: Test cases, verification methods
- ROADMAP.md: Implementation phases, milestones, progress management
- CONTEXT.md: Work context (most important for resuming)
Running AI review (required):
- Run a review on the created documents and code using an AI CLI tool available in the environment.
- Example:
  - gh copilot suggest ...
  - gemini review ...
  - claude ...
- If there are any points raised, reflect them in the revision proposal
User approval:
- Present what has passed the AI review to the user and obtain approval
- After approval, manually create the documents:
- mkdir -p docs/dev/[feature-name]
- Create each file with the appropriate template
Feature registration:
- docs/dev/README.md Add status, priority, and dependencies to
- Project's ROADMAP.md Update if there is any
Tracking the tech stack:
- Question: "What tech stack is used in this project?"
- .meta.json Record in: {"feature": "name", "stack": "stack", "createdAt": "date"}
- Or, from the existing DESIGN.md read
Recording architecture decisions:
- When an important technical decision is made,docs/architecture/decisions/ propose creating an ADR in

Behavior during the session

Monitoring time: Periodically notify the user of the remaining time
5-minute warning: "5 minutes remaining. Please prepare to update CONTEXT.md"
Update proposal:
- When the architecture has changed, DESIGN.md
- When test cases have been added, TEST_PLAN.md
- When a technical decision has been made, CONTEXT.md
Task splitting: If a task exceeds the session time, recommend splitting it

Session end (important)

This is a required step. Never skip it:

AI review of deliverables:
- Run an AI review on the main files created or changed during the session
- Use available CLI tools to obtain an objective evaluation
Record the actual time: "This session was [X] minutes"
CONTEXT.md Update with the following:
- Previous session date and time
- Session work time (start time - end time)
- Session time (actual work time)
- Details of the current work
- Progress status: Completed/In progress/Not started
- Actions for the next session (in priority order)
- Technical notes, findings, issues
- List of changed files
- Environment restoration procedure (if necessary)
ROADMAP.md Update the progress rate of
Update project-level documentation as needed:
- docs/dev/README.md: Feature status update
- ARCHITECTURE.md: If the architecture has changed
- If there is an important decision,docs/architecture/decisions/ Create an ADR in
Recommend Git commits(WIP commits are also acceptable)

CONTEXT.md template

## 前回のセッション
## 前回のセッション
- 日時: [YYYY-MM-DD]
- 作業時間: [HH:MM] - [HH:MM] ([X] min)
- 所要時間: [実際の作業時間]
- タスク: [取り組んだ内容]

## 進捗
- 完了: [完了した作業]
- 進行中: [現在の作業]
- ブロック中: [問題点]

## 次のセッション (優先順位順)
1. [アクション 1] - 優先度: 高
2. [アクション 2] - 優先度: 中

## 技術メモ
- [主要な決定事項や発見]

## 変更されたファイル
- [修正されたファイルのリスト]

## 環境の復元
### セットアップコマンド
[依存関係、環境変数など]

### 実行環境
- Node.js: [バージョン]
- その他のツール: [バージョン]

### ハードウェア状態 (IoT/電子工作)
- GPIO ピン: [接続状態]

Tech stack management

Priority order for determining the tech stack:

In the feature directory, .meta.json read if present
DESIGN.md infer from the contents of
Ask the user: "What tech stack are you using for this project?"
For future sessions, .meta.json record in

Documentation support

Help the user organize information into structured documentation:

Convert requirements into the SPEC.md format
Organize design discussions into DESIGN.md summarize in
Test cases TEST_PLAN.md in a table format
Structure the work plan into ROADMAP.md phases

Integration into existing projects

When working on a project without structured documentation:

Assess the current state:
- Check existing documentation (README, docs/, wiki, etc.)
- Identify the project's maturity (new/growing/mature)
Propose a documentation structure based on project scale:
- Small/new: Minimal structure (README + docs/dev/)
- Growing: Add ARCHITECTURE.md + docs/dev/README.md
- Mature: Full structure including architecture/, guides/, api/
If the user rejects the full structure:
- Create a minimal CONTEXT.md in an appropriate location
- Ask the user where to store the session context
- Respect the user's preferences while recommending best practices
Migration path: Propose gradually evolving the documentation as the project grows

Helper scripts (Advanced)

scripts/manage-dev.ts exists, andand only if the user explicitly requests it:

Assist with automatic creation of directories/files
Provide a progress summary
Generate templates

Default behavior: Unless instructed otherwise by the user, always use standard commands (mkdir, direct file creation).

Best practices

Flexible session: Consult with the user about the required time (options of 15/30/45/60/90 minutes)
Securing documentation time: Always wrap up work 5-10 minutes before the session ends
CONTEXT.md is mandatory: This is a message to your future self
Appropriate task breakdown: Make sure tasks are completed within the session time
Frequent commits: Small commits, WIP is OK too
Documenting decisions: Always record the rationale for technical decisions
Documentation first: Whenever possible, write documentation before code
Record actual time: CONTEXT.md Record the actual work time in
Two-layer thinking: Consider the impact on both the overall project and the feature level
Architectural consistency: Verify that new features fit the existing architecture
ADR for major decisions: Create Architecture Decision Records for important choices

Focus on the workflow and documentation structure, not on specific tools.

Project documentation structure

Recommended complete structure

project-root/
├── README.md                    # プロジェクト概要 (必須)
├── ARCHITECTURE.md             # システム全体のアーキテクチャ
├── CONTRIBUTING.md             # 貢献ガイドライン
├── CHANGELOG.md                # リリース履歴
│
├── docs/
│   ├── README.md              # ドキュメントインデックス
│   ├── getting-started/       # オンボーディングガイド
│   │   ├── installation.md
│   │   ├── quickstart.md
│   │   └── configuration.md
│   │
│   ├── architecture/          # システム設計
│   │   ├── overview.md       # システム概要
│   │   ├── components.md     # コンポーネント構成
│   │   ├── data-flow.md      # データフロー図
│   │   └── decisions/        # ADR (Architecture Decision Records)
│   │       ├── 001-database-choice.md
│   │       ├── 002-api-design.md
│   │       └── template.md
│   │
│   ├── api/                   # API 仕様
│   │   ├── rest-api.md
│   │   └── graphql-schema.md
│   │
│   ├── guides/                # 開発者ガイド
│   │   ├── coding-standards.md
│   │   ├── testing.md
│   │   └── deployment.md
│   │
│   └── dev/                   # アクティブな機能開発
│       ├── README.md          # アクティブな機能インデックス
│       └── [feature-name]/    # 機能ごとのドキュメント
│           ├── SPEC.md
│           ├── DESIGN.md
│           ├── TEST_PLAN.md
│           ├── ROADMAP.md
│           └── CONTEXT.md

Minimal structure (small projects)

project-root/
├── README.md                    # プロジェクト概要
├── ARCHITECTURE.md             # 基本的なアーキテクチャメモ
└── docs/
    └── dev/
        ├── README.md          # アクティブな機能
        └── [feature-name]/
            ├── SPEC.md
            ├── DESIGN.md
            └── CONTEXT.md

Documentation maturity levels

Level 1 - Startup (less than 3 months, 1-2 developers):

README.md
docs/dev/[feature]/CONTEXT.md

Level 2 - Growing (3-12 months, 2-5 developers):

- ARCHITECTURE.md
- docs/dev/README.md
- docs/getting-started/

Level 3 - Mature (1 year or more, 5 or more developers):

- docs/architecture/decisions/ (ADRs)
- docs/guides/
- docs/api/
- CONTRIBUTING.md