Skip to content

feat: Design architecting-act skill for LangGraph projects - #4

Merged
qjrm1430 merged 3 commits into
mainfrom
claude/architecting-act-skill-011UJzXp5fV574z5CmHiJ8YP
Nov 15, 2025
Merged

feat: Design architecting-act skill for LangGraph projects#4
qjrm1430 merged 3 commits into
mainfrom
claude/architecting-act-skill-011UJzXp5fV574z5CmHiJ8YP

Conversation

@qjrm1430

@qjrm1430 qjrm1430 commented Nov 15, 2025

Copy link
Copy Markdown
Member

✅ Review Readiness Checklist (Required before review)

Complete all items below before marking your PR ready for review. After completion, delete these instructions and replace with your actual PR message.

  • PR title format: {TYPE}({SCOPE}): {DESCRIPTION}

    • Examples:
      • feat(cli): add cast scaffolding option
      • fix(scaffold): resolve snake_case normalization bug
      • docs(readme): clarify Python 3.12+ requirement
    • Allowed {TYPE} values:
      • feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert, release
    • Allowed {SCOPE} values (optional): project area
      • cli, scaffold, utils, docs, tests, workflow, cookiecutter
    • Once you've written the title, delete this checklist item.
  • PR message: Replace this entire checklist with the template below

    • Description: Describe the change. Include a linking a pull request to an issue keyword if applicable.
    • Issue: The related issue number (e.g., Fixes #123)
    • Dependencies: Any dependencies required for this change
    • SNS handle: If announced publicly, add your handle for a shoutout
  • Add tests and docs: If you add a new feature/integration, include

    1. Tests: Prefer unit tests without network access (integration tests as needed)
    2. Docs/examples: Update user-facing docs/examples
      • Update README.md or scaffold template docs (e.g., act_operator/act_operator/scaffold/{{ cookiecutter.project_dir }}/README.md)
  • Lint and test: From the root of modified package(s), run and ensure all pass

    uv run ruff check .
    uv run pytest -q

    We will not consider a PR unless these two pass in CI. See CONTRIBUTING.md for more.

Additional guidelines

  • Import optional dependencies inside functions (lazy import).
  • Do not add dependencies to pyproject.toml (even optional) unless required for runtime/tests.
  • Most PRs should modify only one area/scope.
  • Changes must be backwards compatible.

📝 Summary

📄 Description

🔗 Issue / Dependencies / Mentions

  • Issue:
  • Dependencies:
  • SNS handle:

✅ Local Checks

  • uv run ruff check . passed
  • uv run pytest -q passed

💡 Notes (Optional)

🔗 Related Issue(s)

…esign

Add comprehensive skill for designing LangGraph architectures through
interactive 4-stage process. This skill guides users through architectural
decisions before implementation, generating formalized CLAUDE.md documents.

Features:
- 4-stage interactive workflow (Understand → Constraints → Design → Finalize)
- 6 decision framework resources (patterns, state, nodes, edges, subgraphs, anti-patterns)
- Automated architecture validation script (anti-pattern detection)
- CLAUDE.md generation script (interactive & CLI modes)
- Template-based documentation generation
- LangGraph 1.0 focused (verified against official docs)
- SOLID principles for node architecture
- No code in resources (conceptual/decision frameworks only)

Components:
- SKILL.md: Main interactive guide (404 lines, ~3.2k tokens)
- Resources: Decision frameworks (~17k tokens total)
  * workflow-patterns.md: Pattern selection (ReAct, Plan-Execute, etc.)
  * state-design-guide.md: State schema design with reducers
  * node-architecture-guide.md: SOLID node decomposition
  * edge-routing-guide.md: Conditional routing strategies
  * subgraph-decisions.md: When/how to use subgraphs
  * anti-patterns.md: Common mistakes and fixes
- Scripts:
  * generate_claude_md.py: Interactive CLAUDE.md generator
  * validate_architecture.py: Architecture validation tool
- Templates:
  * CLAUDE.md.template: Architecture document template

Token efficiency:
- Frequently accessed resources <2k tokens (patterns, anti-patterns)
- All resources <4k tokens (under primary constraint)
- Total skill ~18.5k tokens

Integration:
- First skill in 4-skill Act Operator skillset
- Outputs CLAUDE.md for developing-cast skill handoff
- Validates against LangGraph 1.0 best practices

Also update .gitignore to allow skills in template while excluding
test projects.
Add exception to .gitignore to include skills in the scaffold template
while still excluding test/sample projects ending in -act/.
Add comprehensive skill for automating Act project management through
scripts and clear command guidance. Focus on maximum automation and
token efficiency.

Features:
- 5 automation scripts (save 100-900 tokens per use)
- Command cheat sheet SKILL.md (~1.1k tokens)
- 3 quick reference resources (~3.6k tokens total)
- Total skill: ~7k tokens (highly optimized)
- All scripts tested and working

Scripts:
- create_cast.py: Create cast with full boilerplate (~300 tokens saved)
  * Extends `act cast -c` with complete module structure
  * Adds state.py, models.py, agents.py, tools.py, prompts.py
  * Proper imports, type hints, and docstrings
- project_info.py: Display project status (~150 tokens saved)
  * Shows Python version, packages, casts, dependencies
  * Single command vs multiple queries
- validate_project.py: Check structure and config (~200 tokens saved)
  * Validates files, directories, pyproject.toml
  * Checks cast structures and workspace config
  * --fix flag for automatic repairs
- batch_dependencies.py: Batch add/remove packages (~100 tokens saved)
  * Add/remove multiple packages in one command
  * Dev dependency support
- sync_check.py: Sync with change tracking (~100 tokens saved)
  * Shows added/removed packages after sync
  * --all-extras for dev/test/lint groups

Resources:
- uv-commands.md: Essential uv command reference (~825 tokens)
  * Dependency management, environment sync, tools
  * Common workflows and best practices
- cast-structure.md: Cast directory layout (~1.4k tokens)
  * Standard structure, file purposes, import patterns
  * Minimal vs full boilerplate options
- troubleshooting.md: Common issues and fixes (~1.4k tokens)
  * Environment, dependency, cast, LangGraph issues
  * Symptom → Fix → Explanation format

Design Philosophy:
- Scripts do the work, not Claude
- SKILL.md is command index, not tutorial
- Resources are quick lookup, not manuals
- Minimum 100-token savings per script
- Maximum automation for developer productivity

Token Efficiency:
- SKILL.md: ~1,146 tokens (<2k target, <5k limit)
- Resources: <2k tokens each
- Total context: ~7k tokens (highly optimized)
- ROI: Skill pays for itself after ~6 operations

Integration:
- Skill 2 of 4 in Act Operator skillset
- Bridges architecting-act (CLAUDE.md) → developing-cast
- Handles all project setup and environment management
@qjrm1430
qjrm1430 merged commit 0f14f35 into main Nov 15, 2025
3 checks passed
@qjrm1430 qjrm1430 self-assigned this Nov 15, 2025
@qjrm1430
qjrm1430 deleted the claude/architecting-act-skill-011UJzXp5fV574z5CmHiJ8YP branch December 5, 2025 06:12
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.

2 participants