From c4fcbe2e3be6eafc6221aed40ef3674ceac116b3 Mon Sep 17 00:00:00 2001 From: itdove Date: Tue, 31 Mar 2026 13:39:04 -0400 Subject: [PATCH] docs: replace DAF_AGENTS.md with skill-based workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace DAF_AGENTS.md references with daf-workflow skill - Update command reference from `config edit` to `config show` - Add deprecation notes for file-based workflow approach - Consolidate workflow docs under skills system 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- AGENTS.md | 31 +-- CLAUDE.md | 2 +- README.md | 5 - devflow/cli/commands/new_command.py | 1 - devflow/cli_skills/daf-jira-fields/SKILL.md | 3 +- devflow/utils/daf_agents_validation.py | 9 +- docs/context-templates/JIRA.md | 2 +- docs/context-templates/README.md | 3 +- docs/developer/publishing-to-pypi.md | 14 +- docs/getting-started/installation.md | 225 -------------------- docs/reference/configuration.md | 1 - 11 files changed, 31 insertions(+), 265 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c2280b9..c783dcb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ **IMPORTANT**: The following general instructions apply to the DevAIFlow project and MUST be followed when contributing to this codebase. -**For JIRA operations**: This project uses the `daf` tool for issue tracker integration. Always use `daf jira` commands (documented in DAF_AGENTS.md), NOT direct API calls. +**For JIRA operations**: This project uses the `daf` tool for issue tracker integration. Always use `daf jira` commands (documented in the daf-workflow skill), NOT direct API calls. **Skills Documentation**: The skills (CLI command documentation) are located in the **`devflow/cli_skills/`** directory in the repository. @@ -211,12 +211,12 @@ When creating pull requests, the `Assisted-by: ` field i ### DevAIFlow (daf tool) -**IMPORTANT**: For instructions on using the `daf` tool (DevAIFlow) for JIRA operations, session management, and workflows, see [DAF_AGENTS.md](DAF_AGENTS.md). +**IMPORTANT**: For instructions on using the `daf` tool (DevAIFlow) for JIRA operations, session management, and workflows, see the **daf-workflow skill**. -The DAF_AGENTS.md file is automatically loaded when you open sessions via `daf open` and contains: +The daf-workflow skill is automatically loaded when you open sessions and contains: - Complete `daf jira` command reference - Session management workflows -- JIRA integration best practices +- Issue tracker integration (JIRA, GitHub Issues, GitLab Issues) - Configuration and troubleshooting **Quick reference:** @@ -224,9 +224,9 @@ The DAF_AGENTS.md file is automatically loaded when you open sessions via `daf o - Create JIRA issues: `daf jira create {bug|story|task} --summary "..." --parent PROJ-12345` - Update JIRA issues: `daf jira update PROJ-12345 --description "..."` - Session management: `daf new`, `daf open`, `daf complete` -- Configuration: `daf config edit` +- Configuration: `daf config show` -For complete documentation, refer to DAF_AGENTS.md. +For complete documentation, refer to the daf-workflow, daf-cli, and daf-jira-fields skills. #### Safety Guards: Commands That Cannot Run Inside Claude Code @@ -1526,22 +1526,13 @@ class Session(BaseModel): - Prominent placement in JIRA Integration section of skill - Updated "Tips for Claude Code Sessions" to lead with Wiki markup requirement - Skills deployed to workspace via daf skills command - - Makes Wiki markup requirement more visible than DAF_AGENTS.md alone + - Makes Wiki markup requirement more visible in daf-cli skill - Addresses issue of Claude forgetting to use JIRA Wiki markup in daf jira new sessions - All 1229 tests pass -- ✓ Automatic version check and upgrade prompt for DAF_AGENTS.md - - Added `_get_bundled_daf_agents_content()` to read bundled file content for comparison - - Added `_check_and_upgrade_daf_agents()` to detect outdated installations and prompt for upgrade - - Modified `_validate_context_files()` to call upgrade check after finding DAF_AGENTS.md - - Content comparison detects when installed file differs from bundled version - - Prompts user: "DAF_AGENTS.md has been updated. Would you like to upgrade to the latest version?" - - User can accept (upgrade), decline (continue with current), or auto-upgrade in mock mode - - Upgrade works for both repository and workspace installations - - Non-blocking: session continues if upgrade declined or if bundled file cannot be read - - Follows same pattern as `devflow/utils/claude_commands.py` for consistency - - Comprehensive test coverage: 10 new tests covering all scenarios - - All 1556 tests pass - - Documentation updated in docs/02-installation.md with upgrade behavior explanation +- ✓ Automatic version check and upgrade prompt for DAF_AGENTS.md (DEPRECATED - replaced by daf-workflow skill in v0.2.0) + - Note: DAF_AGENTS.md was removed in favor of the daf-workflow skill (see CHANGELOG.md for migration details) + - Migration logic helps users transition from DAF_AGENTS.md to daf-workflow skill + - All workflow guidance now provided through skills (daf-workflow, daf-cli, daf-jira-fields) - ✓ Official Windows OS support for DevAIFlow - Fixed SIGTERM signal handling in 4 command files (new_command.py, investigate_command.py, open_command.py, jira_new_command.py) - Windows uses SIGBREAK instead of Unix SIGTERM for graceful shutdown diff --git a/CLAUDE.md b/CLAUDE.md index 6b81ba1..35cdb6f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,4 +2,4 @@ See [AGENTS.md](AGENTS.md) for detailed project information and coding guidelines. -**For daf tool usage instructions:** See [DAF_AGENTS.md](DAF_AGENTS.md) - This file is automatically loaded when you open sessions via `daf open` and provides comprehensive guidance on using daf commands, JIRA integration, and workflows. +**For daf tool usage instructions:** See the **daf-workflow skill** - This skill is automatically loaded when you open sessions and provides comprehensive guidance on using daf commands, issue tracker integration, and workflows. diff --git a/README.md b/README.md index d4ba869..570976c 100644 --- a/README.md +++ b/README.md @@ -550,11 +550,6 @@ DevAIFlow supports the following environment variables for customization: - Settings stored in `$DEVAIFLOW_HOME/` directory - Personal preferences only, no team sharing -5. **Copy DAF_AGENTS.md**: Copy the `DAF_AGENTS.md` file to your project roots for automatic daf tool guidance in AI assistant sessions - - This file is automatically loaded when opening sessions - - Provides complete command reference and best practices - - Customize JIRA templates to match your organization's standards - **Configuration Files:** - `backends/jira.json` - JIRA backend settings (URL, field mappings, transitions) - `organization.json` - Organization-wide settings (project, field aliases) diff --git a/devflow/cli/commands/new_command.py b/devflow/cli/commands/new_command.py index 07eb1cf..f022ab4 100644 --- a/devflow/cli/commands/new_command.py +++ b/devflow/cli/commands/new_command.py @@ -124,7 +124,6 @@ def _generate_initial_prompt( Please start by reading the following context files if they exist: - AGENTS.md (agent-specific instructions) - CLAUDE.md (project guidelines and standards) - - DAF_AGENTS.md (daf tool usage guide) Also read the issue tracker ticket: daf jira view PROJ-52470" diff --git a/devflow/cli_skills/daf-jira-fields/SKILL.md b/devflow/cli_skills/daf-jira-fields/SKILL.md index f0787eb..5f8d0ee 100644 --- a/devflow/cli_skills/daf-jira-fields/SKILL.md +++ b/devflow/cli_skills/daf-jira-fields/SKILL.md @@ -274,4 +274,5 @@ daf config show --json | jq '.jira.field_mappings' - **daf-jira skill** - daf commands for validated JIRA operations - **daf-jira-mcp skill** - Using MCP tools with daf intelligence - **daf-config skill** - View configuration and field mappings -- **DAF_AGENTS.md** - JIRA templates and workflows +- **daf-workflow skill** - Workflow guidance and issue tracker integration +- **ORGANIZATION.md** - JIRA templates and organization standards diff --git a/devflow/utils/daf_agents_validation.py b/devflow/utils/daf_agents_validation.py index e1c3cfa..5039e68 100644 --- a/devflow/utils/daf_agents_validation.py +++ b/devflow/utils/daf_agents_validation.py @@ -1,4 +1,11 @@ -"""Utility functions for validating DAF_AGENTS.md context files.""" +"""Migration utilities for DAF_AGENTS.md to daf-workflow skill transition. + +NOTE: DAF_AGENTS.md was deprecated in v0.2.0 and replaced by the daf-workflow skill. +This module helps users migrate by offering to delete old DAF_AGENTS.md files. + +The daf-workflow skill provides all workflow guidance and is automatically loaded +by Claude Code, eliminating the need for DAF_AGENTS.md files. +""" import importlib.resources import shutil diff --git a/docs/context-templates/JIRA.md b/docs/context-templates/JIRA.md index a8b7c13..134dcda 100644 --- a/docs/context-templates/JIRA.md +++ b/docs/context-templates/JIRA.md @@ -65,4 +65,4 @@ run command ## Complete Reference -See DAF_AGENTS.md for the complete JIRA Wiki markup reference and additional JIRA integration guidelines. +See the **daf-workflow skill** and **ORGANIZATION.md** for JIRA Wiki markup reference and JIRA integration guidelines. diff --git a/docs/context-templates/README.md b/docs/context-templates/README.md index 2e04376..8fe475f 100644 --- a/docs/context-templates/README.md +++ b/docs/context-templates/README.md @@ -9,7 +9,6 @@ Context files are loaded in this order: 1. **Default files** (from project directory): - AGENTS.md (agent-specific instructions) - CLAUDE.md (project guidelines and standards) - - DAF_AGENTS.md (daf tool usage guide) 2. **Backend context** (from DEVAIFLOW_HOME): - `backends/JIRA.md` - JIRA-specific integration rules @@ -266,4 +265,4 @@ daf new --name test-context --goal "Test context loading" - User-configured context: `daf config context --help` - AGENTS.md: Project-specific agent instructions - CLAUDE.md: Project guidelines and standards -- DAF_AGENTS.md: DevAIFlow tool usage guide +- Skills: daf-workflow, daf-cli, daf-jira-fields (auto-loaded) diff --git a/docs/developer/publishing-to-pypi.md b/docs/developer/publishing-to-pypi.md index 711e758..314d751 100644 --- a/docs/developer/publishing-to-pypi.md +++ b/docs/developer/publishing-to-pypi.md @@ -175,8 +175,8 @@ unzip -l dist/devaiflow-*.whl | head -30 Verify important files are included: - `LICENSE` - `README.md` -- `DAF_AGENTS.md` - All Python modules in `devflow/` +- Skills in `devflow/cli_skills/` ## Testing on TestPyPI @@ -470,7 +470,7 @@ ERROR File already exists. See https://pypi.org/help/#file-name-reuse ### Missing Files in Package -**Problem:** Important files (like `LICENSE`, `DAF_AGENTS.md`) are missing from the uploaded package. +**Problem:** Important files (like `LICENSE`, skills) are missing from the uploaded package. **Cause:** Files not included in package manifest. @@ -480,16 +480,16 @@ ERROR File already exists. See https://pypi.org/help/#file-name-reuse ``` include LICENSE include README.md - include DAF_AGENTS.md + recursive-include devflow/cli_skills *.md ``` 2. **Verify with setup.py:** ```python setup( include_package_data=True, - data_files=[ - ("", ["DAF_AGENTS.md"]), - ], + package_data={ + 'devflow': ['cli_skills/*/*.md'], + }, ... ) ``` @@ -497,7 +497,7 @@ ERROR File already exists. See https://pypi.org/help/#file-name-reuse 3. **Inspect package contents before uploading:** ```bash tar -tzf dist/devaiflow-*.tar.gz | grep LICENSE - tar -tzf dist/devaiflow-*.tar.gz | grep DAF_AGENTS.md + tar -tzf dist/devaiflow-*.tar.gz | grep cli_skills ``` ### Command Not Found: twine diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 83d78e1..b3e89a7 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -727,231 +727,6 @@ rm -rf $DEVAIFLOW_HOME **Note:** This does NOT delete your Claude Code conversation files in `~/.claude/projects/`. -## Setting Up DAF_AGENTS.md (Required) - -**IMPORTANT:** DAF_AGENTS.md is **required** for Claude Code sessions. When you run `daf open`, the tool validates that DAF_AGENTS.md exists before launching Claude. - -### Where to Place DAF_AGENTS.md - -DAF_AGENTS.md can be placed in one of two locations (checked in this order): - -**Option 1: Repository Directory (Recommended for Customization)** - -Place DAF_AGENTS.md in your project repository for project-specific customization: - -```bash -# Copy to your project repository -cp /path/to/devaiflow/DAF_AGENTS.md ~/your-project/ -cd ~/your-project -git add DAF_AGENTS.md -git commit -m "Add DAF_AGENTS.md" -``` - -**Benefits:** -- ✅ Customize JIRA templates for this specific project -- ✅ Version controlled with your project -- ✅ Different customizations per project - -**Option 2: Workspace Directory (Shared Across All Projects)** - -Place DAF_AGENTS.md in your workspace root to share it across all projects: - -```bash -# Copy to workspace (e.g., ~/development/workspace/) -cp /path/to/devaiflow/DAF_AGENTS.md ~/development/workspace/ -``` - -**Benefits:** -- ✅ One file shared across all projects in the workspace -- ✅ Easier maintenance (update once, affects all projects) -- ✅ Good for standardized workflows across many projects - -### Lookup Order - -When you run `daf open`, the tool searches for DAF_AGENTS.md in this order: - -1. **Repository directory** (`~/your-project/DAF_AGENTS.md`) - Project-specific -2. **Workspace directory** (`~/your-workspace/DAF_AGENTS.md`) - Shared -3. **Error** - If not found in either location, Claude Code won't start - -**Example error if not found:** -``` -✗ DAF_AGENTS.md not found - -Searched locations: - 1. Repository: /Users/you/my-project/DAF_AGENTS.md - 2. Workspace: /Users/you/workspace/DAF_AGENTS.md -``` - -### Automatic Installation and Upgrades - -**Auto-Installation on First Use** - -If DAF_AGENTS.md is not found, `daf open` will offer to install the bundled version automatically: - -``` -⚠ DAF_AGENTS.md not found - -DAF_AGENTS.md provides daf tool usage instructions to Claude. - -Install DAF_AGENTS.md now? -This will copy the bundled DAF_AGENTS.md to: /Users/you/my-project/DAF_AGENTS.md -Install DAF_AGENTS.md to repository? [y/n] (y): -``` - -**Auto-Upgrade Detection** - -When you upgrade the daf package (via `pip install --upgrade devaiflow`), the bundled DAF_AGENTS.md may contain improvements: -- New command documentation -- Updated JIRA Wiki markup guidance -- Improved workflow instructions -- Template updates - -When you run `daf open`, the tool automatically detects if your installed DAF_AGENTS.md is outdated by comparing content with the bundled version. If different, you'll see: - -``` -⚠ DAF_AGENTS.md has been updated -The bundled version contains newer documentation and command updates. - -Upgrade DAF_AGENTS.md to the latest version? -This will replace: /Users/you/my-project/DAF_AGENTS.md -Upgrade to latest version? [y/n] (y): -``` - -**Upgrade Behavior:** -- **Accept (y)**: Replaces your installed file with the latest bundled version -- **Decline (n)**: Continues with your current version (session opens normally) -- **Mock mode**: Auto-upgrades without prompting (for automated testing) - -**Note:** If you've customized DAF_AGENTS.md (e.g., modified JIRA templates), the upgrade will overwrite your changes. Before accepting, consider backing up your customizations. - -### What DAF_AGENTS.md Provides - -- Complete daf tool command reference -- JIRA integration workflows and templates -- Git and PR/MR creation guidelines -- Session management best practices -- Troubleshooting tips - -**Note:** DAF_AGENTS.md is automatically read as a default context file (like AGENTS.md and CLAUDE.md) when you run `daf open`. You don't need to configure it manually. - -### Customizing for Your Organization - -**IMPORTANT**: DAF_AGENTS.md uses generic placeholders (PROJECT, YourWorkstream, gitlab.example.com) intentionally. Actual values are configured in `$DEVAIFLOW_HOME/config.json` via `daf config` commands, NOT by editing DAF_AGENTS.md. - -#### Configuration: What Goes Where - -**Configured in `$DEVAIFLOW_HOME/config.json` (via `daf config`):** -- ✅ JIRA URL, project key, workstream -- ✅ Affected version for bugs -- ✅ Field mappings (acceptance_criteria, epic_link, etc.) -- ✅ Workflow settings (auto-add summary, auto-create PR, etc.) -- ✅ Repository paths and detection settings -- ✅ Claude model and AI settings -- ✅ Git remote URLs (detected from `git remote -v`) - -**Customized in DAF_AGENTS.md (manual editing):** -- ✅ JIRA issue templates (Epic, Story, Bug, Task format) -- ✅ Organization-specific workflows and best practices - -That's it! Most configuration is automatic or done via `daf config`. - -#### Configure Settings via `daf config` - -```bash -# Interactive configuration (recommended) -daf config edit -``` - -**What's configurable** (via `daf config edit` TUI): -- **JIRA Tab:** URL, project, workstream, field mappings, visibility -- **Repository Tab:** Workspace path, detection method, branch naming -- **Claude Tab:** Model selection, temperature, Vertex AI settings -- **Session Workflow Tab:** Testing prompts, PR/MR auto-creation -- **Advanced Tab:** Context files, export settings - -#### Customize DAF_AGENTS.md Templates - -**The ONE thing to customize in DAF_AGENTS.md:** - -**JIRA Issue Templates** ⭐ - -Location: Search for `#### JIRA Issue Templates` in DAF_AGENTS.md - -These templates define the structure for issues created with `daf jira create`. Customize to match your organization's JIRA standards: - -```bash -# 1. Copy DAF_AGENTS.md to your project -cp /path/to/devaiflow/DAF_AGENTS.md ~/my-project/ - -# 2. Edit JIRA templates -cd ~/my-project -vim DAF_AGENTS.md -# Find: #### JIRA Issue Templates -# Customize: Epic, Story, Bug, Task, Spike templates to match your org -``` - -**Why customize templates?** -Every organization has different JIRA standards: -- Required sections and field names -- Format requirements (Jira Wiki markup style) -- Company-specific information to include -- Validation and approval workflows - -**Example - Your organization's Bug Template might require:** -``` -h3. *Problem Statement* - - -h3. *Environment* -- Version: -- Platform: - -h3. *Business Impact* -- Severity: -- Users affected: - -h3. *Steps to Reproduce* -1. -2. -``` - -Instead of the generic template provided. - -#### Complete Setup Example - -```bash -# 1. Configure via daf config -daf config edit -# Set: JIRA URL, project, workstream, affected version, etc. - -# 2. Copy DAF_AGENTS.md -cp /path/to/devaiflow/DAF_AGENTS.md ~/my-project/ -cd ~/my-project - -# 3. Customize JIRA templates -vim DAF_AGENTS.md -# Navigate to "#### JIRA Issue Templates" -# Edit Epic, Story, Bug, Task formats to match your org's standards - -# 4. Commit to version control -git add DAF_AGENTS.md -git commit -m "Add customized DAF_AGENTS.md for our team" -``` - -### Key Takeaways - -**DO NOT edit DAF_AGENTS.md to add:** -- Project keys, workstreams, JIRA URLs → Use `daf config` -- GitLab/GitHub hostnames → Auto-detected from `git remote -v` -- Repository paths → Use `daf config` - -**DO edit DAF_AGENTS.md only to customize:** -- JIRA issue template formats (Epic, Story, Bug, Task, Spike) -- Organization-specific best practices (optional) - -DAF_AGENTS.md is generic by design - it uses placeholders that are filled in at runtime from your `$DEVAIFLOW_HOME/config.json` and git configuration. - ## Configuring Claude Code Permissions **CRITICAL**: Claude Code must be configured to allow reading context files from `$DEVAIFLOW_HOME/` and `$DEVAIFLOW_HOME/`. Without this, the tool will fail when Claude tries to read organization context files. diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index e1de3eb..ab74021 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -1321,7 +1321,6 @@ When you create or open a session, context files are loaded in this order: 1. **Default files** (from project directory): - `AGENTS.md` (agent-specific instructions) - `CLAUDE.md` (project guidelines and standards) - - `DAF_AGENTS.md` (daf tool usage guide) 2. **Backend context** (from DEVAIFLOW_HOME): - `backends/JIRA.md` (JIRA-specific integration rules)