Skip to content

Fix: Standardize outputs/ and improve GitHub token guidance#10

Merged
tkstang merged 1 commit intomainfrom
output-fixes
Mar 10, 2026
Merged

Fix: Standardize outputs/ and improve GitHub token guidance#10
tkstang merged 1 commit intomainfrom
output-fixes

Conversation

@tkstang
Copy link
Owner

@tkstang tkstang commented Feb 14, 2026

Summary

This PR addresses two important consistency and usability issues:

  1. Standardize on outputs/ directory across all skills
  2. Add dual output (in-thread + file) to analysis skills
  3. Improve GitHub token scope requirements for organization discovery

Changes

1. Directory Standardization

Before: Mixed use of generated/ (IC skills) and outputs/ (manager skills)
After: Consistent use of outputs/ everywhere

  • ✅ Updated all IC skills to use <profile-root>/outputs/
  • ✅ Updated AGENTS.md to reflect new structure
  • ✅ Added clarifying comment to .gitignore
  • ✅ Consistent paths across IC and manager modes

Files updated:

  • AGENTS.md
  • .gitignore
  • 6 skill files

2. Dual Output for Analysis Skills

Problem: Skills like detect-projects, detect-themes, summarize-work only responded in-thread. Users had no persistent file to reference later.

Solution: All skills now do BOTH:

  1. Respond in-thread (for MCP integration and immediate feedback)
  2. Save to file in outputs/ (for persistence and future reference)

Skills updated:

  • work-chronicler-detect-projectsoutputs/projects-detected-YYYY-MM-DD.md
  • work-chronicler-detect-themesoutputs/themes-detected-YYYY-MM-DD.md
  • work-chronicler-summarize-workoutputs/work-summary-YYYY-MM-DD.md
  • work-chronicler-generate-resume-bulletsoutputs/resume-bullets-YYYY-MM-DD.md
  • work-chronicler-write-self-reviewoutputs/self-review-YYYY-MM-DD.md
  • work-chronicler-update-resumeoutputs/resume-updated-YYYY-MM-DD.md

3. GitHub Token Scope Requirements

Problem: read:org scope requirement wasn't clear, causing auto-discovery to fail for organizations.

Solution:

  • ✅ Updated README with clear scope requirements
  • ✅ Updated token prompts in init wizard (IC and manager mode)
  • ✅ Updated auto-discovery option description to mention read:org requirement
  • ✅ Better error handling: detects INSUFFICIENT_SCOPES and shows helpful message

Example improved error:

GitHub token is missing the 'read:org' scope, which is required to query organizations.
Please add this scope at: https://github.com/settings/tokens

Files Changed

  • Skills (6): Dual output + outputs/ paths
  • Init (3): Better token guidance and error messages
  • Docs (3): AGENTS.md, README.md, .gitignore

Testing

  • Verified all skills mention dual output requirement
  • Confirmed consistent use of outputs/ directory
  • Tested init flow shows clear token requirements
  • Error handling tested with missing read:org scope

Impact

  • Better UX: Users get both immediate feedback AND persistent files
  • Consistency: All skills use the same directory structure
  • Clearer guidance: Token requirements are explicit and well-documented
  • Better errors: Users know exactly what to fix when discovery fails

This commit addresses two issues:

1. Standardize on "outputs/" directory across all skills
   - Updated all IC skills to use outputs/ instead of generated/
   - Updated AGENTS.md to reflect outputs/ as standard location
   - Added clarifying comment to .gitignore
   - Consistent paths: <profile-root>/outputs/ (IC) and reports/<id>/outputs/ (manager)

2. Add dual output to analysis skills
   - Skills now both respond in-thread AND save to file
   - In-thread response works with MCP and provides immediate feedback
   - File output provides persistence for later reference
   - Updated: detect-projects, detect-themes, summarize-work, generate-resume-bullets,
     write-self-review, update-resume

3. Improve GitHub token scope requirements
   - Clearly document read:org scope requirement for org discovery
   - Update token prompts in init wizard (both IC and manager mode)
   - Update auto-discovery option description to mention read:org
   - Better error handling: detect INSUFFICIENT_SCOPES and show helpful message
   - Update README with clear scope requirements

Files changed:
- Skills: 6 skills updated with dual output and outputs/ paths
- Init: Better token guidance and error messages
- Docs: AGENTS.md, README.md updated with clear requirements
@tkstang tkstang merged commit 552ebb0 into main Mar 10, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant