Skip to content

refactor(skills): break cross-skill cycles by ownership + canonical-blocks drift guard (T4) - #1459

Closed
RaduAna-Maria wants to merge 1 commit into
fix/rpa-mode-partition-t3from
fix/cross-skill-cycles-t4
Closed

RaduAna-Maria wants to merge 1 commit into
fix/rpa-mode-partition-t3from
fix/cross-skill-cycles-t4

Conversation

@RaduAna-Maria

Copy link
Copy Markdown
Collaborator

Summary

Tranche 4, stacked on #1458. Eliminates all three bidirectional cross-skill documentation cycles via ownership assignment, and introduces the canonical-blocks mechanism — the durable fix for cross-skill boilerplate drift that keeps skills physically self-contained.

Cycles eliminated (allowlist ratchet: 15 → 10 edges, 0 cycles)

Cycle Links removed Ownership decision
agents ↔ maestro-flow 13 maestro-flow owns flow-node JSON + flow-variable semantics; uipath-agents owns building/prompting/deploying the agent. Handoff via the already-documented Skill invocation (agents quickstart step 10). No JSON shape duplicated across skills.
maestro-flow hitl plugin ↔ uipath-human-in-the-loop 5 HITL skill owns schema contracts, conversion rules, app-task variant; the plugin keeps its quick reference. Stale "skills are self-contained, links for context only" disclaimers deleted.
test ↔ rpa 1 (back-link) rpa owns pack flags; downstream rpa→test edge kept.

scripts/check-cross-skill-links.py's ALLOWED_EDGES shrunk accordingly — CI now blocks reintroduction of any of these edges. Remaining 10 edges are the documented architecture (platform-IS, governance→admin, rpa→solution/test chain, hitl→tasks).

Canonical blocks

New mechanism preserving the isolation rule while killing drift: each skill keeps its own physical copy of shared boilerplate between <!-- BEGIN/END CANONICAL: <id> --> markers; assets/canonical-blocks/<id>.md is the single source; scripts/check-canonical-blocks.py (CI: validate-canonical-blocks.yml) fails on any byte drift; --write re-stamps all copies. Documented in CONTRIBUTING.md.

First migrated block: uip-cli-resolution (7 occurrences across agents, coded-apps, governance ×2, human-in-the-loop, maestro-case, maestro-flow). Unifying the copies surfaced 4 real bugs the drift had already caused:

  • /bin/uip appended outside the command substitution in coded-apps and human-in-the-loop — produces a broken path whenever uip IS on PATH
  • wrong fallback path (node_modules/uip/bin/uip) in agents lowcode
  • wrong package name @uipath/uipcli in 4 governance locations (the real package is @uipath/cli)
  • no doc copy carried the --@uipath:registry scope pin that hooks/ensure-uip.sh (the actual SessionStart installer) deliberately applies — canonical block now matches the hook

Validation

  • scripts/check-canonical-blocks.py — OK, 1 block, 7 occurrences byte-identical
  • scripts/check-cross-skill-links.py — OK with the shrunken allowlist
  • scripts/check-skill-status.py — OK; description hook — all pass
  • All links in changed files resolve; remaining sibling-skill mentions are prose (skill names), not paths

🤖 Generated with Claude Code

…nical-blocks drift guard

Cycles (all 3 bidirectional cycles eliminated; allowlist 15 → 10 edges, 0 cycles):
- agents ↔ maestro-flow (13 deep links): maestro-flow owns flow-node JSON
  shapes and flow-variable semantics; uipath-agents owns building/prompting/
  deploying the agent. Deep relative links replaced with ownership prose;
  the documented Skill-invocation handoff carries the transition. No JSON
  shape was copied across skills — single source of truth preserved.
- maestro-flow hitl plugin ↔ uipath-human-in-the-loop (5 links): HITL skill
  owns schema contracts/conversion rules/app-task variant; plugin keeps its
  quick reference. Now-pointless self-containment disclaimers deleted.
- test → rpa back-link removed (rpa owns pack flags; downstream rpa→test
  edge kept). hitl planning.md option table aligned with the 2a/2b split.

Canonical blocks (drift guard for cross-skill boilerplate):
- assets/canonical-blocks/<id>.md + scripts/check-canonical-blocks.py
  (--write to stamp, --list, --json) + validate-canonical-blocks.yml CI.
  Skills keep physical copies between BEGIN/END CANONICAL markers; CI fails
  on byte drift. Documented in CONTRIBUTING.md.
- First block uip-cli-resolution stamped in 7 locations. Fixed real bugs
  found while unifying: /bin/uip appended outside the command substitution
  in coded-apps and human-in-the-loop (broken path when uip is on PATH),
  wrong fallback package path in agents lowcode, wrong package name
  @uipath/uipcli in 4 governance spots, and aligned the install command
  with hooks/ensure-uip.sh's registry-scope flag

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Jun 12, 2026 •

Copy link
Copy Markdown
Contributor

Claude finished @RaduAna-Maria's task in 4m 23s —— View job


PR Review: Cross-Skill Cycles & Canonical Blocks

  • Gather context (review criteria, project conventions, existing comments)
  • Read full diff against base branch
  • Review new files (canonical-blocks script, CI workflow, canonical block)
  • Review modified skill files for correctness
  • Check cross-skill references and link resolution
  • Check for secrets/tokens/personal paths
  • Post review findings

Summary

Tranche 4 eliminates three bidirectional cross-skill doc cycles (agents ↔ maestro-flow, maestro-flow ↔ hitl, test → rpa back-link) by assigning clear ownership and replacing cross-skill markdown links with prose pointers ("load that skill for X"). It also introduces the canonical-blocks mechanism — a CI-enforced drift guard for shared boilerplate — and uses it to unify the uip CLI resolution block across 7 skills, fixing 4 real bugs in the process.

Change-by-Change Review

1. scripts/check-canonical-blocks.py (new, 266 lines)

OK — Well-structured validation script. The parser handles edge cases: unterminated markers, mismatched IDs, nested BEGINs, orphaned canonical files. The --write mode re-scans after stamping so marker-sanity findings still fail CI. The --list mode is useful for maintainability.

One minor note: when a BEGIN/END id mismatch is found (line 114-119), the occurrence is still recorded with the mismatched boundary. This is fine — the mismatch error causes CI failure regardless, and continuing the parse avoids cascading false positives. Clean design.

2. .github/workflows/validate-canonical-blocks.yml (new)

OK — Minimal CI job. Path filters correctly scope to skills/**/*.md, canonical-block sources, the script, and the workflow itself. Uses actions/checkout@v4 and setup-python@v5. No issues.

3. assets/canonical-blocks/uip-cli-resolution.md (new)

OK — The canonical block fixes all 4 bugs called out in the PR description:

  • echo "$(…)" wrapping fixes the broken-path bug (old: || npm root -g … | sed …)/bin/uip — the /bin/uip was outside the command substitution)
  • Package name @uipath/cli (not @uipath/uipcli)
  • Correct fallback path (sed 's|/node_modules$||' + /bin/uip)
  • --@uipath:registry=https://registry.npmjs.org/ scope pin matches the SessionStart hook

4. CONTRIBUTING.md

OK — Clean documentation of the canonical-blocks mechanism. The marker example is inside a fenced code block, so the script won't match it (it only scans skills/**/*.md).

5. scripts/check-cross-skill-links.py — allowlist shrink

OK — Removed 5 edges (agents ↔ maestro-flow bidirectional, maestro-flow ↔ hitl bidirectional, test → rpa). Remaining 10 edges are the documented architecture. The ratchet is tighter.

6. skills/uipath-agents/references/coded/embedding-in-flows.md

OK — Three cross-skill links replaced with prose pointers. The =js: warning paragraph (line 405) now says "Full flow-variable semantics live in the uipath-maestro-flow skill" — accurate ownership assignment.

7. skills/uipath-agents/references/coded/flow-integration.md

OK — Two cross-skill links replaced. Node JSON shape ownership correctly attributed to maestro-flow's agent plugin.

8. skills/uipath-agents/references/lowcode/agent-prompting-guide.md

OK — Inline-in-flow token wiring reference replaced with prose. Added useful context about contentTokens[] rawString requiring leading/trailing space.

9. skills/uipath-agents/references/lowcode/capabilities/inline-in-flow/inline-in-flow.md

OK — Cross-skill link to maestro-flow's inline-agent impl replaced.

10. skills/uipath-agents/references/lowcode/project-lifecycle.md

OK — Old buggy which uip || … xargs resolution replaced with canonical block. Clean integration.

11. skills/uipath-coded-apps/SKILL.md

OK — The old CLI setup had the /bin/uip outside the command substitution (the original bug). Now fixed with canonical block. The code block is cleanly split: canonical block for resolution, then skill-specific uip tools install commands in a separate block.

12. skills/uipath-governance/SKILL.md

OK — Fixed @uipath/uipcli → @uipath/cli (line 50). This is an inline mention, not a Step 0 block, so it's correct to not wrap it in canonical markers.

13. skills/uipath-governance/references/access-policy/access-policy-overview-guide.md

OK — Old which uip && uip --version + npm install -g @uipath/uipcli replaced with canonical block. Both bugs fixed.

14. skills/uipath-governance/references/aops-policy/aops-policy-commands.md

OK — Error table fix: @uipath/uipcli → @uipath/cli.

15. skills/uipath-governance/references/aops-policy/aops-policy-overview-guide.md

OK — Same canonical block substitution as the access-policy counterpart.

16. skills/uipath-human-in-the-loop/SKILL.md

OK — Old buggy resolution (missing echo "$(…)" wrapper) replaced with canonical block. Added install section that was previously missing.

17. skills/uipath-human-in-the-loop/references/hitl-node-quickform.md

OK — Two cross-skill links removed. The CLI reference now points to the owning SKILL.md. The $vars path link replaced with prose.

18. skills/uipath-maestro-case/references/planning.md

OK — Canonical block cleanly separated from the case-specific version-check logic. The npm view command also gained the --@uipath:registry flag — good consistency fix.

19. skills/uipath-maestro-flow/references/author/references/plugins/agent/impl.md

OK — Two cross-skill links removed. The "For resource file format" section collapsed from a 3-line bullet list to a single prose sentence.

20. skills/uipath-maestro-flow/references/author/references/plugins/agent/planning.md

OK — Cross-skill link to coded-vs-lowcode-guide replaced with prose.

21. skills/uipath-maestro-flow/references/author/references/plugins/hitl/impl.md

OK — Stale "Skills are self-contained. This cross-skill reference is for documentation context only" disclaimer removed. Two cross-skill links replaced with prose ownership pointers. Clean.

22. skills/uipath-maestro-flow/references/author/references/plugins/hitl/planning.md

OK — Similar cleanup. The table on line 12 was corrected to include both uipath.human-in-the-loop with inputs.type="custom" and the resource node variant — this is a correctness improvement.

23. skills/uipath-maestro-flow/references/author/references/plugins/inline-agent/impl.md

OK — Three cross-skill links replaced with prose pointers. The "Source of truth" callout updated from "linked above" to "named above" — accurate since they're now prose references, not links.

24. skills/uipath-maestro-flow/references/shared/cli-conventions.md

OK — Canonical block integrated with clean separation: block ends at line 24, then CURRENT=$($UIP --version ...) for version-prefix detection follows outside markers.

25. skills/uipath-test/references/publish-and-link-guide.md

OK — Cross-skill link to rpa's publishing-guide replaced with prose. The pack flags reference correctly notes ownership.

What's Missing

Nothing identified. The PR is well-scoped — cycle elimination + canonical blocks + bug fixes, with no drive-by changes to unrelated functionality.

Area Ratings

Area Status Notes
Frontmatter OK No frontmatter changes in this PR
E2E Tests OK No new skills added; existing skill behavior unchanged
Skill Body OK All changes are link→prose replacements and canonical block insertions
References & Assets OK New assets/canonical-blocks/ directory well-structured
Repo Hygiene OK No secrets, no personal paths, CODEOWNERS adequate (wildcard covers new paths), scoped changes

Issues for Manual Review

  • Domain accuracy of the canonical block's shell command: The echo "$(npm root -g 2>/dev/null | sed 's|/node_modules$||')/bin/uip" fallback assumes @uipath/cli installs a bin/uip binary under the npm global prefix. Confirm this matches the actual package layout of @uipath/cli — if the binary name or location changed, all 7 occurrences would be wrong simultaneously (the canonical mechanism makes this a single-point-of-failure by design, which is both a strength and a risk).
  • HITL planning table update (hitl/planning.md:12): The table now lists uipath.human-in-the-loop with inputs.type="custom" as an alternative to uipath.core.human-task.{key}. Verify this accurately reflects the runtime's current capability.

Conclusion

Clean, well-executed PR. The cycle elimination is thorough — all cross-skill markdown links in the affected files are replaced with prose ownership pointers, and the allowlist ratchet is tightened accordingly. The canonical-blocks mechanism is well-designed (marker-based with CI enforcement, --write for automated stamping, --list for inventory). The first migrated block fixes 4 real bugs. No issues found that would block merge.

@RaduAna-Maria
RaduAna-Maria marked this pull request as draft June 12, 2026 15:59
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