deepwork 0.3.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

deepwork/standard_jobs/deepwork_jobs/steps/review_job_spec.md

@@ -0,0 +1,208 @@
+# Review Job Specification
+
+## Objective
+
+Review the `job.yml` created in the define step against the doc spec quality criteria using a sub-agent for unbiased evaluation, then iterate on fixes until all criteria pass.
+
+## Why This Step Exists
+
+The define step focuses on understanding user requirements and creating a job specification. This review step ensures the specification meets quality standards before implementation. Using a sub-agent provides an unbiased "fresh eyes" review that catches issues the main agent might miss after being deeply involved in the definition process.
+
+## Task
+
+Use a sub-agent to review the job.yml against all 9 doc spec quality criteria, then fix any failed criteria. Repeat until all criteria pass.
+
+### Step 1: Read the Job Specification
+
+Read the `job.yml` file created in the define step:
+
+```
+.deepwork/jobs/[job_name]/job.yml
+```
+
+Also read the doc spec for reference:
+
+```
+.deepwork/doc_specs/job_spec.md
+```
+
+### Step 2: Spawn Review Sub-Agent
+
+Use the Task tool to spawn a sub-agent that will provide an unbiased review:
+
+```
+Task tool parameters:
+- subagent_type: "general-purpose"
+- model: "haiku"
+- description: "Review job.yml against doc spec"
+- prompt: [see below]
+```
+
+**Sub-agent prompt template:**
+
+```
+Review this job.yml against the following 9 quality criteria from the doc spec.
+
+For each criterion, respond with:
+- PASS or FAIL
+- If FAIL: specific issue and suggested fix
+
+## job.yml Content
+
+[paste the full job.yml content here]
+
+## Quality Criteria
+
+1. **Valid Identifier**: Job name must be lowercase with underscores, no spaces or special characters (e.g., `competitive_research`, `monthly_report`)
+
+2. **Semantic Version**: Version must follow semantic versioning format X.Y.Z (e.g., `1.0.0`, `2.1.3`)
+
+3. **Concise Summary**: Summary must be under 200 characters and clearly describe what the job accomplishes
+
+4. **Rich Description**: Description must be multi-line and explain: the problem solved, the process, expected outcomes, and target users
+
+5. **Changelog Present**: Must include a changelog array with at least the initial version entry
+
+6. **Complete Steps**: Each step must have: id (lowercase_underscores), name, description, instructions_file, outputs (at least one), and dependencies array
+
+7. **Valid Dependencies**: Dependencies must reference existing step IDs with no circular references
+
+8. **Input Consistency**: File inputs with `from_step` must reference a step that is in the dependencies array
+
+9. **Output Paths**: Outputs must be valid filenames or paths (e.g., `report.md` or `reports/analysis.md`)
+
+## Response Format
+
+Respond with a structured evaluation:
+
+### Overall: [X/9 PASS]
+
+### Criterion Results
+
+1. Valid Identifier: [PASS/FAIL]
+   [If FAIL: Issue and fix]
+
+2. Semantic Version: [PASS/FAIL]
+   [If FAIL: Issue and fix]
+
+[... continue for all 9 criteria ...]
+
+### Summary of Required Fixes
+
+[List any fixes needed, or "No fixes required - all criteria pass"]
+```
+
+### Step 3: Review Sub-Agent Findings
+
+Parse the sub-agent's response:
+
+1. **Count passing criteria** - How many of the 9 criteria passed?
+2. **Identify failures** - List specific criteria that failed
+3. **Note suggested fixes** - What changes does the sub-agent recommend?
+
+### Step 4: Fix Failed Criteria
+
+For each failed criterion, edit the job.yml to address the issue:
+
+**Common fixes by criterion:**
+
+| Criterion | Common Issue | Fix |
+|-----------|-------------|-----|
+| Valid Identifier | Spaces or uppercase | Convert to lowercase_underscores |
+| Semantic Version | Missing or invalid format | Set to `"1.0.0"` or fix format |
+| Concise Summary | Too long or vague | Shorten to <200 chars, be specific |
+| Rich Description | Single line or missing context | Add multi-line explanation with problem/process/outcome/users |
+| Changelog Present | Missing changelog | Add `changelog:` with initial version entry |
+| Complete Steps | Missing required fields | Add id, name, description, instructions_file, outputs, dependencies |
+| Valid Dependencies | Non-existent step or circular | Fix step ID reference or reorder dependencies |
+| Input Consistency | from_step not in dependencies | Add the referenced step to dependencies array |
+| Output Paths | Invalid characters or format | Use valid filename/path format |
+
+### Step 5: Re-Run Review (If Needed)
+
+If any criteria failed:
+
+1. **Spawn a new sub-agent** with the updated job.yml content
+2. **Review the new findings**
+3. **Fix any remaining issues**
+4. **Repeat until all 9 criteria pass**
+
+### Step 6: Confirm Completion
+
+When all 9 criteria pass:
+
+1. **Announce success**: "All 9 doc spec quality criteria pass."
+2. **List what was validated**:
+   - Valid Identifier
+   - Semantic Version
+   - Concise Summary
+   - Rich Description
+   - Changelog Present
+   - Complete Steps
+   - Valid Dependencies
+   - Input Consistency
+   - Output Paths
+3. **Include the promise**: `<promise>Quality Criteria Met</promise>`
+4. **Guide to next step**: "Run `/deepwork_jobs.implement` to generate the step instruction files."
+
+## Example Review Cycle
+
+```
+Claude: Let me review the job.yml against the doc spec quality criteria.
+
+[Spawns sub-agent with haiku model]
+
+Sub-agent response:
+### Overall: 7/9 PASS
+
+### Criterion Results
+1. Valid Identifier: PASS
+2. Semantic Version: PASS
+3. Concise Summary: FAIL
+   Issue: Summary is 245 characters, exceeds 200 char limit
+   Fix: Shorten to "Competitive analysis workflow for product positioning"
+4. Rich Description: PASS
+5. Changelog Present: FAIL
+   Issue: No changelog array present
+   Fix: Add changelog with initial version entry
+6. Complete Steps: PASS
+7. Valid Dependencies: PASS
+8. Input Consistency: PASS
+9. Output Paths: PASS
+
+### Summary of Required Fixes
+1. Shorten summary to under 200 characters
+2. Add changelog array with initial version
+
+Claude: I found 2 issues. Let me fix them.
+
+[Edits job.yml to shorten summary and add changelog]
+
+Claude: Let me verify the fixes with another review.
+
+[Spawns new sub-agent]
+
+Sub-agent response:
+### Overall: 9/9 PASS
+
+### Summary of Required Fixes
+No fixes required - all criteria pass
+
+Claude: All 9 doc spec quality criteria pass.
+
+<promise>Quality Criteria Met</promise>
+
+**Next step:** Run `/deepwork_jobs.implement` to generate the step instruction files.
+```
+
+## Quality Criteria
+
+- **Sub-Agent Used**: A sub-agent was spawned to provide unbiased review (not just self-review)
+- **All doc spec Criteria Evaluated**: The sub-agent assessed all 9 quality criteria from the doc spec
+- **Findings Addressed**: All failed criteria were fixed by the main agent
+- **Validation Loop Complete**: The review-fix cycle continued until all criteria passed
+- **Promise Included**: The response includes `<promise>Quality Criteria Met</promise>` when complete
+
+## Output
+
+The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` that passes all 9 doc spec quality criteria.

deepwork/standard_jobs/deepwork_jobs/templates/doc_spec.md.example

@@ -0,0 +1,86 @@
+---
+name: "Monthly AWS Spending Report"
+description: "A Markdown summary of AWS spend across accounts for finance and engineering leadership"
+path_patterns:
+  - "finance/aws-reports/*.md"
+  - "reports/aws/*.md"
+target_audience: "Finance team and Engineering leadership"
+frequency: "Monthly, following AWS invoice arrival"
+quality_criteria:
+  - name: Executive Summary
+    description: Must include a 2-3 sentence summary of total spend, month-over-month change percentage, and top cost driver
+  - name: Visualization
+    description: Must include at least one Mermaid.js chart showing spend breakdown by service (pie chart) or trend over time (line chart)
+  - name: Variance Analysis
+    description: Must compare current month against previous month with percentage changes for top 5 services
+  - name: Cost Attribution
+    description: Must break down costs by team/project using AWS tags where available
+  - name: Action Items
+    description: Must include 2-3 specific, actionable recommendations for cost optimization
+---
+
+# Monthly AWS Spending Report: [Month, Year]
+
+## Executive Summary
+
+[2-3 sentences summarizing:
+- Total spend this month
+- Percentage change from last month
+- The primary cost driver]
+
+## Spend Overview
+
+### Total Spend by Service
+
+```mermaid
+pie title AWS Spend by Service
+    "EC2" : 45
+    "RDS" : 25
+    "S3" : 15
+    "Lambda" : 10
+    "Other" : 5
+```
+
+### Month-over-Month Trend
+
+```mermaid
+xychart-beta
+    title "Monthly AWS Spend Trend"
+    x-axis [Jan, Feb, Mar, Apr, May, Jun]
+    y-axis "Spend ($K)" 0 --> 100
+    line [45, 48, 52, 49, 55, 58]
+```
+
+## Variance Analysis
+
+| Service | Last Month | This Month | Change | % Change |
+|---------|-----------|------------|--------|----------|
+| EC2     | $X,XXX    | $X,XXX     | +$XXX  | +X.X%    |
+| RDS     | $X,XXX    | $X,XXX     | -$XXX  | -X.X%    |
+| S3      | $X,XXX    | $X,XXX     | +$XXX  | +X.X%    |
+| Lambda  | $X,XXX    | $X,XXX     | +$XXX  | +X.X%    |
+| Other   | $X,XXX    | $X,XXX     | +$XXX  | +X.X%    |
+
+## Cost Attribution by Team
+
+| Team/Project | Spend | % of Total |
+|--------------|-------|------------|
+| Platform     | $X,XXX | XX%       |
+| Data         | $X,XXX | XX%       |
+| Product      | $X,XXX | XX%       |
+| Shared       | $X,XXX | XX%       |
+
+## Recommendations
+
+1. **[Action Item 1]**: [Specific recommendation with expected savings]
+2. **[Action Item 2]**: [Specific recommendation with expected savings]
+3. **[Action Item 3]**: [Specific recommendation with expected savings]
+
+## Appendix
+
+### Data Sources
+- AWS Cost Explorer
+- AWS Tags: team, project, environment
+
+### Report Methodology
+[Brief explanation of how costs are calculated and attributed]

deepwork/standard_jobs/deepwork_jobs/templates/doc_spec.md.template

@@ -0,0 +1,26 @@
+---
+name: "[Document Name]"
+description: "[Brief description of the document's purpose]"
+path_patterns:
+  - "[path/to/documents/*.md]"
+target_audience: "[Who reads this document]"
+frequency: "[How often produced, e.g., Monthly, Per sprint, On demand]"
+quality_criteria:
+  - name: "[Criterion Name]"
+    description: "[What this criterion requires - be specific]"
+  - name: "[Criterion Name]"
+    description: "[What this criterion requires - be specific]"
+  - name: "[Criterion Name]"
+    description: "[What this criterion requires - be specific]"
+---
+
+# [Document Title]: [Variables like Month, Year, Sprint]
+
+## Section 1
+[Describe what goes in this section]
+
+## Section 2
+[Describe what goes in this section]
+
+## Section 3
+[Describe what goes in this section]

deepwork/standard_jobs/deepwork_rules/hooks/capture_prompt_work_tree.sh

@@ -8,12 +8,20 @@
 # The baseline contains ALL tracked files (not just changed files) so that
 # the rules_check hook can determine which files are genuinely new vs which
 # files existed before and were just modified.
+#
+# It also captures the HEAD commit ref so that committed changes can be detected
+# by comparing HEAD at Stop time to the captured ref.
 
 set -e
 
 # Ensure .deepwork directory exists
 mkdir -p .deepwork
 
+# Save the current HEAD commit ref for detecting committed changes
+# This is used by get_changed_files_prompt() to detect files changed since prompt,
+# even if those changes were committed during the agent response.
+git rev-parse HEAD > .deepwork/.last_head_ref 2>/dev/null || echo "" > .deepwork/.last_head_ref
+
 # Save ALL tracked files (not just changed files)
 # This is critical for created: mode rules to distinguish between:
 # - Newly created files (not in baseline) -> should trigger created: rules

deepwork/standard_jobs/deepwork_rules/job.yml

@@ -1,6 +1,6 @@
 name: deepwork_rules
-version: "0.3.0"
-summary: "Rules enforcement for AI agent sessions"
+version: "0.4.0"
+summary: "Creates file-change rules that enforce guidelines during AI sessions. Use when automating documentation sync or code review triggers."
 description: |
   Manages rules that automatically trigger when certain files change during an AI agent session.
   Rules help ensure that code changes follow team guidelines, documentation is updated,
@@ -33,11 +33,13 @@ changelog:
     changes: "Standardized on 'ask structured questions' phrasing for user input"
   - version: "0.3.0"
     changes: "Migrated to v2 format - individual markdown files in .deepwork/rules/"
+  - version: "0.4.0"
+    changes: "Improved skill descriptions with third-person voice and 'Use when...' triggers for better discoverability"
 
 steps:
   - id: define
     name: "Define Rule"
-    description: "Create a new rule file in .deepwork/rules/"
+    description: "Creates a rule file that triggers when specified files change. Use when setting up documentation sync, code review requirements, or automated commands."
     instructions_file: steps/define.md
     inputs:
       - name: rule_purpose

deepwork/templates/claude/skill-job-meta.md.jinja

@@ -65,6 +65,13 @@ If user intent is unclear, use AskUserQuestion to clarify:
 - Present available steps as numbered options
 - Let user select the starting point
 
+## Guardrails
+
+- Do NOT copy/paste step instructions directly; always use the Skill tool to invoke steps
+- Do NOT skip steps in the workflow unless the user explicitly requests it
+- Do NOT proceed to the next step if the current step's outputs are incomplete
+- Do NOT make assumptions about user intent; ask for clarification when ambiguous
+
 ## Context Files
 
 - Job definition: `.deepwork/jobs/{{ job_name }}/job.yml`

deepwork/templates/claude/skill-job-step.md.jinja

@@ -46,7 +46,8 @@ user-invocable: false
 {% if quality_criteria or hooks %}
 hooks:
 {% if quality_criteria %}
-  Stop:
+{% for event_name in ["Stop", "SubagentStop"] %}
+  {{ event_name }}:
     - hooks:
         - type: prompt
           prompt: |
@@ -63,14 +64,32 @@ hooks:
             Review the conversation and determine if ALL quality criteria above have been satisfied.
             Look for evidence that each criterion has been addressed.
 
-            If the agent has included `<promise>✓ Quality Criteria Met</promise>` in their response AND
+            If the agent has included `<promise>✓ Quality Criteria Met</promise>` in their response OR
             all criteria appear to be met, respond with: {"ok": true}
 
-            If criteria are NOT met OR the promise tag is missing, respond with:
+            If criteria are NOT met AND the promise tag is missing, respond with:
             {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"}
+{% endfor %}
 {% endif %}
 {% for event_name, event_hooks in hooks.items() %}
-{% if not (event_name == "Stop" and quality_criteria) %}
+{% if not (event_name == "Stop" and quality_criteria) and not (event_name == "SubagentStop" and "Stop" in hooks) %}
+{# For Stop events, generate both Stop and SubagentStop blocks #}
+{% if event_name == "Stop" %}
+{% for stop_event in ["Stop", "SubagentStop"] %}
+  {{ stop_event }}:
+    - hooks:
+{% for hook in event_hooks %}
+{% if hook.type == "script" %}
+        - type: command
+          command: ".deepwork/jobs/{{ job_name }}/{{ hook.path }}"
+{% else %}
+        - type: prompt
+          prompt: |
+            {{ hook.content | indent(12) }}
+{% endif %}
+{% endfor %}
+{% endfor %}
+{% else %}
   {{ event_name }}:
     - hooks:
 {% for hook in event_hooks %}
@@ -84,6 +103,7 @@ hooks:
 {% endif %}
 {% endfor %}
 {% endif %}
+{% endif %}
 {% endfor %}
 {% endif %}
 ---
@@ -149,12 +169,45 @@ Use branch format: `deepwork/{{ job_name }}-[instance]-YYYYMMDD`
 {% if outputs %}
 **Required outputs**:
 {% for output in outputs %}
-- `{{ output }}`{% if output.endswith('/') %} (directory){% endif %}
+- `{{ output.file }}`{% if output.file.endswith('/') %} (directory){% endif %}
+
+{% if output.has_doc_spec and output.doc_spec %}
+  **Doc Spec**: {{ output.doc_spec.name }}
+  > {{ output.doc_spec.description }}
+  **Definition**: `{{ output.doc_spec.path }}`
+{% if output.doc_spec.target_audience %}
+  **Target Audience**: {{ output.doc_spec.target_audience }}
+{% endif %}
+{% if output.doc_spec.quality_criteria %}
+  **Quality Criteria**:
+{% for criterion in output.doc_spec.quality_criteria %}
+  {{ loop.index }}. **{{ criterion.name }}**: {{ criterion.description }}
+{% endfor %}
+{% endif %}
+{% if output.doc_spec.example_document %}
+
+  <details>
+  <summary>Example Document Structure</summary>
+
+  ```markdown
+  {{ output.doc_spec.example_document | indent(2) }}
+  ```
+
+  </details>
+{% endif %}
+{% endif %}
 {% endfor %}
 {% else %}
 No specific file outputs required.
 {% endif %}
 
+## Guardrails
+
+- Do NOT skip prerequisite verification if this step has dependencies
+- Do NOT produce partial outputs; complete all required outputs before finishing
+- Do NOT proceed without required inputs; ask the user if any are missing
+- Do NOT modify files outside the scope of this step's defined outputs
+
 {% if quality_criteria or stop_hooks %}
 ## Quality Validation
 
@@ -180,12 +233,12 @@ Stop hooks will automatically validate your work. The loop continues until all c
 
 {% if is_standalone %}
 1. Verify outputs are created
-2. Inform user: "{{ step_id }} complete{% if outputs %}, outputs: {{ outputs | join(', ') }}{% endif %}"
+2. Inform user: "{{ step_id }} complete{% if outputs %}, outputs: {{ outputs | map(attribute='file') | join(', ') }}{% endif %}"
 
 This standalone skill can be re-run anytime.
 {% else %}
 1. Verify outputs are created
-2. Inform user: "Step {{ step_number }}/{{ total_steps }} complete{% if outputs %}, outputs: {{ outputs | join(', ') }}{% endif %}"
+2. Inform user: "Step {{ step_number }}/{{ total_steps }} complete{% if outputs %}, outputs: {{ outputs | map(attribute='file') | join(', ') }}{% endif %}"
 {% if next_step %}
 3. **Continue workflow**: Use Skill tool to invoke `/{{ job_name }}.{{ next_step }}`
 {% else %}

deepwork/templates/gemini/skill-job-step.toml.jinja

@@ -106,7 +106,22 @@ Use branch format: `deepwork/{{ job_name }}-[instance]-YYYYMMDD`
 {% if outputs %}
 **Required outputs**:
 {% for output in outputs %}
-- `{{ output }}`{% if output.endswith('/') %} (directory){% endif %}
+- `{{ output.file }}`{% if output.file.endswith('/') %} (directory){% endif %}
+
+{% if output.has_doc_spec and output.doc_spec %}
+  **Doc Spec**: {{ output.doc_spec.name }}
+  > {{ output.doc_spec.description }}
+  **Definition**: `{{ output.doc_spec.path }}`
+{% if output.doc_spec.target_audience %}
+  **Target Audience**: {{ output.doc_spec.target_audience }}
+{% endif %}
+{% if output.doc_spec.quality_criteria %}
+  **Quality Criteria**:
+{% for criterion in output.doc_spec.quality_criteria %}
+  {{ loop.index }}. **{{ criterion.name }}**: {{ criterion.description }}
+{% endfor %}
+{% endif %}
+{% endif %}
 {% endfor %}
 {% else %}
 No specific file outputs required.
@@ -128,12 +143,12 @@ No specific file outputs required.
 
 {% if is_standalone %}
 1. Verify outputs are created
-2. Inform user: "{{ step_id }} complete{% if outputs %}, outputs: {{ outputs | join(', ') }}{% endif %}"
+2. Inform user: "{{ step_id }} complete{% if outputs %}, outputs: {{ outputs | map(attribute='file') | join(', ') }}{% endif %}"
 
 This standalone command can be re-run anytime.
 {% else %}
 1. Verify outputs are created
-2. Inform user: "Step {{ step_number }}/{{ total_steps }} complete{% if outputs %}, outputs: {{ outputs | join(', ') }}{% endif %}"
+2. Inform user: "Step {{ step_number }}/{{ total_steps }} complete{% if outputs %}, outputs: {{ outputs | map(attribute='file') | join(', ') }}{% endif %}"
 {% if next_step %}
 3. **Tell user next command**: `/{{ job_name }}:{{ next_step }}`
 {% else %}

deepwork/utils/fs.py

@@ -1,9 +1,43 @@
 """Filesystem utilities for safe file operations."""
 
 import shutil
+import stat
 from pathlib import Path
 
 
+def fix_permissions(path: Path | str) -> None:
+    """
+    Fix file permissions after copying to ensure files are user-writable.
+
+    This is needed because shutil.copytree/copy preserve source permissions,
+    and if the source was installed with restrictive permissions (e.g., read-only),
+    the copied files would also be read-only.
+
+    For directories: Sets rwx for user (0o700 minimum)
+    For files: Sets rw for user (0o600 minimum), preserves executable bit
+
+    Args:
+        path: File or directory path to fix permissions for
+    """
+    path_obj = Path(path)
+
+    if path_obj.is_file():
+        # Get current permissions
+        current_mode = path_obj.stat().st_mode
+        # Ensure user can read and write, preserve executable bit
+        new_mode = current_mode | stat.S_IRUSR | stat.S_IWUSR
+        path_obj.chmod(new_mode)
+    elif path_obj.is_dir():
+        # Fix directory permissions first (need execute to traverse)
+        current_mode = path_obj.stat().st_mode
+        new_mode = current_mode | stat.S_IRWXU  # rwx for user
+        path_obj.chmod(new_mode)
+
+        # Recursively fix all contents
+        for item in path_obj.iterdir():
+            fix_permissions(item)
+
+
 def ensure_dir(path: Path | str) -> Path:
     """
     Create directory if it doesn't exist.
@@ -94,6 +128,8 @@ def copy_dir(src: Path | str, dst: Path | str, ignore_patterns: list[str] | None
         ignore_func = _ignore
 
     shutil.copytree(src_path, dst_path, ignore=ignore_func, dirs_exist_ok=True)
+    # Fix permissions - source may have restrictive permissions (e.g., read-only)
+    fix_permissions(dst_path)
 
 
 def find_files(directory: Path | str, pattern: str) -> list[Path]:

deepwork/utils/yaml_utils.py

@@ -69,6 +69,30 @@ def save_yaml(path: Path | str, data: dict[str, Any]) -> None:
         raise YAMLError(f"Failed to write YAML file {path_obj}: {e}") from e
 
 
+def load_yaml_from_string(content: str) -> dict[str, Any] | None:
+    """
+    Load YAML from a string and return parsed data.
+
+    Args:
+        content: YAML content as string
+
+    Returns:
+        Parsed YAML data as dictionary, or None if content is empty
+
+    Raises:
+        YAMLError: If YAML parsing fails
+    """
+    try:
+        data = yaml.safe_load(content)
+        if data is None:
+            return None
+        if not isinstance(data, dict):
+            raise YAMLError(f"YAML content must be a dictionary, got {type(data).__name__}")
+        return data
+    except yaml.YAMLError as e:
+        raise YAMLError(f"Failed to parse YAML content: {e}") from e
+
+
 def validate_yaml_structure(data: dict[str, Any], required_keys: list[str]) -> None:
     """
     Validate that YAML data contains required keys.

{deepwork-0.3.1.dist-info → deepwork-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepwork
-Version: 0.3.1
+Version: 0.4.0
 Summary: Framework for enabling AI agents to perform complex, multi-step work tasks
 Project-URL: Homepage, https://github.com/deepwork/deepwork
 Project-URL: Documentation, https://github.com/deepwork/deepwork#readme
@@ -73,7 +73,11 @@ Please fully install https://pypi.org/project/deepwork/ and make sure you see th
 ### Install DeepWork
 
 ```bash
-# Using pipx (recommended - isolated environment)
+# Using Homebrew (macOS/Linux)
+brew tap unsupervisedcom/deepwork
+brew install deepwork
+
+# Using pipx (isolated environment)
 pipx install deepwork
 
 # Or using uv
@@ -235,7 +239,39 @@ your-project/
 ## Documentation
 
 - **[Architecture](doc/architecture.md)**: Complete design specification
+- **[Doc Specs](doc/doc-specs.md)**: Document specification format for output quality criteria
 - **[Contributing](CONTRIBUTING.md)**: Setup development environment and contribute
+- **[Nix Flakes Guide](doc/nix-flake.md)**: Comprehensive guide for using DeepWork with Nix flakes
+
+## Development with Nix
+
+DeepWork is available as a Nix flake for reproducible development environments:
+
+```bash
+# Using Nix flakes
+nix develop
+
+# Or with direnv (automatic activation - recommended)
+echo "use flake" > .envrc
+direnv allow
+```
+
+The Nix environment provides all dependencies including Python 3.11, uv, pytest, ruff, and mypy.
+
+### Installing DeepWork from Flake
+
+You can also install deepwork directly from the flake:
+
+```bash
+# Install deepwork from this flake
+nix profile install github:Unsupervisedcom/deepwork
+
+# Or run it without installing
+nix run github:Unsupervisedcom/deepwork -- --help
+
+# Or build the package
+nix build github:Unsupervisedcom/deepwork
+```
 
 ## Project Structure
 
@@ -276,6 +312,7 @@ Define structured, multi-step workflows where each step has clear requirements a
 - **Artifact Passing**: Seamlessly use file outputs from one step as inputs for future steps.
 - **Dynamic Inputs**: Support for both fixed file references and interactive user parameters.
 - **Human-Readable YAML**: Simple, declarative job definitions that are easy to version and maintain.
+- **Doc Specs**: Reference doc specs to enforce quality criteria on document outputs (see [doc specs documentation](doc/doc-specs.md)).
 
 ### Git-Native Workflow
 Maintain a clean repository with automatic branch management and isolation.