1name: Documentation Automation
2
3on:
4 # push:
5 # branches: [main]
6 # paths:
7 # - 'crates/**'
8 # - 'extensions/**'
9 workflow_dispatch:
10 inputs:
11 pr_number:
12 description: 'PR number to analyze (gets full PR diff)'
13 required: false
14 type: string
15 trigger_sha:
16 description: 'Commit SHA to analyze (ignored if pr_number is set)'
17 required: false
18 type: string
19
20permissions:
21 contents: write
22 pull-requests: write
23
24env:
25 FACTORY_API_KEY: ${{ secrets.FACTORY_API_KEY }}
26 DROID_MODEL: claude-opus-4-5-20251101
27
28jobs:
29 docs-automation:
30 runs-on: ubuntu-latest
31 timeout-minutes: 30
32
33 steps:
34 - name: Checkout repository
35 uses: actions/checkout@v4
36 with:
37 fetch-depth: 0
38
39 - name: Install Droid CLI
40 id: install-droid
41 run: |
42 curl -fsSL https://app.factory.ai/cli | sh
43 echo "${HOME}/.local/bin" >> "$GITHUB_PATH"
44 echo "DROID_BIN=${HOME}/.local/bin/droid" >> "$GITHUB_ENV"
45 # Verify installation
46 "${HOME}/.local/bin/droid" --version
47
48 - name: Setup Node.js (for Prettier)
49 uses: actions/setup-node@v4
50 with:
51 node-version: '20'
52
53 - name: Install Prettier
54 run: npm install -g prettier
55
56 - name: Get changed files
57 id: changed
58 run: |
59 if [ -n "${{ inputs.pr_number }}" ]; then
60 # Get full PR diff
61 echo "Analyzing PR #${{ inputs.pr_number }}"
62 echo "source=pr" >> "$GITHUB_OUTPUT"
63 echo "ref=${{ inputs.pr_number }}" >> "$GITHUB_OUTPUT"
64 gh pr diff "${{ inputs.pr_number }}" --name-only > /tmp/changed_files.txt
65 elif [ -n "${{ inputs.trigger_sha }}" ]; then
66 # Get single commit diff
67 SHA="${{ inputs.trigger_sha }}"
68 echo "Analyzing commit $SHA"
69 echo "source=commit" >> "$GITHUB_OUTPUT"
70 echo "ref=$SHA" >> "$GITHUB_OUTPUT"
71 git diff --name-only "${SHA}^" "$SHA" > /tmp/changed_files.txt
72 else
73 # Default to current commit
74 SHA="${{ github.sha }}"
75 echo "Analyzing commit $SHA"
76 echo "source=commit" >> "$GITHUB_OUTPUT"
77 echo "ref=$SHA" >> "$GITHUB_OUTPUT"
78 git diff --name-only "${SHA}^" "$SHA" > /tmp/changed_files.txt || git diff --name-only HEAD~1 HEAD > /tmp/changed_files.txt
79 fi
80
81 echo "Changed files:"
82 cat /tmp/changed_files.txt
83 env:
84 GH_TOKEN: ${{ github.token }}
85
86 # Phase 0: Guardrails are loaded via AGENTS.md in each phase
87
88 # Phase 2: Explore Repository (Read-Only - default)
89 - name: "Phase 2: Explore Repository"
90 id: phase2
91 run: |
92 "$DROID_BIN" exec \
93 -m "$DROID_MODEL" \
94 -f .factory/prompts/docs-automation/phase2-explore.md \
95 > /tmp/phase2-output.txt 2>&1 || true
96 echo "Repository exploration complete"
97 cat /tmp/phase2-output.txt
98
99 # Phase 3: Analyze Changes (Read-Only - default)
100 - name: "Phase 3: Analyze Changes"
101 id: phase3
102 run: |
103 CHANGED_FILES=$(tr '\n' ' ' < /tmp/changed_files.txt)
104 echo "Analyzing changes in: $CHANGED_FILES"
105
106 # Build prompt with context
107 cat > /tmp/phase3-prompt.md << 'EOF'
108 $(cat .factory/prompts/docs-automation/phase3-analyze.md)
109
110 ## Context
111
112 ### Changed Files
113 $CHANGED_FILES
114
115 ### Phase 2 Output
116 $(cat /tmp/phase2-output.txt)
117 EOF
118
119 "$DROID_BIN" exec \
120 -m "$DROID_MODEL" \
121 "$(cat .factory/prompts/docs-automation/phase3-analyze.md)
122
123 Changed files: $CHANGED_FILES" \
124 > /tmp/phase3-output.md 2>&1 || true
125 echo "Change analysis complete"
126 cat /tmp/phase3-output.md
127
128 # Phase 4: Plan Documentation Impact (Read-Only - default)
129 - name: "Phase 4: Plan Documentation Impact"
130 id: phase4
131 run: |
132 "$DROID_BIN" exec \
133 -m "$DROID_MODEL" \
134 -f .factory/prompts/docs-automation/phase4-plan.md \
135 > /tmp/phase4-plan.md 2>&1 || true
136 echo "Documentation plan complete"
137 cat /tmp/phase4-plan.md
138
139 # Check if updates are required
140 if grep -q "NO_UPDATES_REQUIRED" /tmp/phase4-plan.md; then
141 echo "updates_required=false" >> "$GITHUB_OUTPUT"
142 else
143 echo "updates_required=true" >> "$GITHUB_OUTPUT"
144 fi
145
146 # Phase 5: Apply Plan (Write-Enabled with --auto medium)
147 - name: "Phase 5: Apply Documentation Plan"
148 id: phase5
149 if: steps.phase4.outputs.updates_required == 'true'
150 run: |
151 "$DROID_BIN" exec \
152 -m "$DROID_MODEL" \
153 --auto medium \
154 -f .factory/prompts/docs-automation/phase5-apply.md \
155 > /tmp/phase5-report.md 2>&1 || true
156 echo "Documentation updates applied"
157 cat /tmp/phase5-report.md
158
159 # Phase 5b: Format with Prettier
160 - name: "Phase 5b: Format with Prettier"
161 id: phase5b
162 if: steps.phase4.outputs.updates_required == 'true'
163 run: |
164 echo "Formatting documentation with Prettier..."
165 cd docs && prettier --write src/
166
167 echo "Verifying Prettier formatting passes..."
168 cd docs && prettier --check src/
169
170 echo "Prettier formatting complete"
171
172 # Phase 6: Summarize Changes (Read-Only - default)
173 - name: "Phase 6: Summarize Changes"
174 id: phase6
175 if: steps.phase4.outputs.updates_required == 'true'
176 run: |
177 # Get git diff of docs
178 git diff docs/src/ > /tmp/docs-diff.txt || true
179
180 "$DROID_BIN" exec \
181 -m "$DROID_MODEL" \
182 -f .factory/prompts/docs-automation/phase6-summarize.md \
183 > /tmp/phase6-summary.md 2>&1 || true
184 echo "Summary generated"
185 cat /tmp/phase6-summary.md
186
187 # Phase 7: Commit and Open PR
188 - name: "Phase 7: Create PR"
189 id: phase7
190 if: steps.phase4.outputs.updates_required == 'true'
191 run: |
192 # Check if there are actual changes
193 if git diff --quiet docs/src/; then
194 echo "No documentation changes detected"
195 exit 0
196 fi
197
198 # Configure git
199 git config user.name "factory-droid[bot]"
200 git config user.email "138933559+factory-droid[bot]@users.noreply.github.com"
201
202 # Daily batch branch - one branch per day, multiple commits accumulate
203 BRANCH_NAME="docs/auto-update-$(date +%Y-%m-%d)"
204
205 # Stash local changes from phase 5
206 git stash push -m "docs-automation-changes" -- docs/src/
207
208 # Check if branch already exists on remote
209 if git ls-remote --exit-code --heads origin "$BRANCH_NAME" > /dev/null 2>&1; then
210 echo "Branch $BRANCH_NAME exists, checking out and updating..."
211 git fetch origin "$BRANCH_NAME"
212 git checkout -B "$BRANCH_NAME" "origin/$BRANCH_NAME"
213 else
214 echo "Creating new branch $BRANCH_NAME..."
215 git checkout -b "$BRANCH_NAME"
216 fi
217
218 # Apply stashed changes
219 git stash pop || true
220
221 # Stage and commit
222 git add docs/src/
223 SUMMARY=$(head -50 < /tmp/phase6-summary.md)
224 git commit -m "docs: auto-update documentation
225
226 ${SUMMARY}
227
228 Triggered by: ${{ steps.changed.outputs.source }} ${{ steps.changed.outputs.ref }}
229
230 Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>"
231
232 # Push
233 git push -u origin "$BRANCH_NAME"
234
235 # Check if PR already exists for this branch
236 EXISTING_PR=$(gh pr list --head "$BRANCH_NAME" --json number --jq '.[0].number' || echo "")
237
238 if [ -n "$EXISTING_PR" ]; then
239 echo "PR #$EXISTING_PR already exists for branch $BRANCH_NAME, updated with new commit"
240 else
241 # Create new PR
242 gh pr create \
243 --title "docs: automated documentation update ($(date +%Y-%m-%d))" \
244 --body-file /tmp/phase6-summary.md \
245 --base main || true
246 echo "PR created on branch: $BRANCH_NAME"
247 fi
248 env:
249 GH_TOKEN: ${{ github.token }}
250
251 # Summary output
252 - name: "Summary"
253 if: always()
254 run: |
255 echo "## Documentation Automation Summary" >> "$GITHUB_STEP_SUMMARY"
256 echo "" >> "$GITHUB_STEP_SUMMARY"
257
258 if [ "${{ steps.phase4.outputs.updates_required }}" == "false" ]; then
259 echo "No documentation updates required for this change." >> "$GITHUB_STEP_SUMMARY"
260 elif [ -f /tmp/phase6-summary.md ]; then
261 cat /tmp/phase6-summary.md >> "$GITHUB_STEP_SUMMARY"
262 else
263 echo "Workflow completed. Check individual phase outputs for details." >> "$GITHUB_STEP_SUMMARY"
264 fi