Skip to main content
documentation-placement Document placement using timeline test and HestAI visibility rules. Maps artifacts to .hestai-sys/, .hestai/, docs/, .hestai/state/ with phase artifact rules, format selection, anti-patterns, and documentation-first protocols.
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/elevanaltd/HestAI-MCP --skill documentation-placementThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... Related occupations SOC
Based on SOC occupation classification
name documentation-placement description Document placement using timeline test and HestAI visibility rules. Maps artifacts to .hestai-sys/, .hestai/, docs/, .hestai/state/ with phase artifact rules, format selection, anti-patterns, and documentation-first protocols. allowed-tools ["Read","Write","Bash"] triggers ["documentation placement","ADR placement","phase artifact","documentation first","B1 migration gate","visibility rules"]
===DOCUMENTATION_PLACEMENT===
META:
TYPE::SKILL
VERSION::"2.3"
STATUS::ACTIVE
COMPRESSION_TIER::AGGRESSIVE
DOMAIN::HERMES[communication]+HESTIA[structure]
§1::CORE_PRINCIPLE
TIMELINE_TEST::[
IF[document_before_code]â.hestai/north-star/|.hestai/rules/,
IF[document_describes_implementation]âdocs/,
IF[document_guides_implementation]âdocs/,
IF[operational_state_or_tracking]â.hestai/state/context/,
IF[session_or_handoff]â.hestai/state/sessions/
]
RATIONALE::"Timelineâplacement: planning=.hestai/, implementation=docs/, operational=.hestai/state/"
CANONICAL_REFERENCE::.hestai-sys/standards/rules/visibility-rules.oct.md
§2::REPOSITORY_STRUCTURE
// Per visibility-rules.oct.md v1.7
SYSTEM_GOVERNANCE[.hestai-sys/]::[
READ_ONLY[injected_from_src/hestai_mcp/_bundled_hub/],
standards/workflow/â"System North Star (000-SYSTEM-HESTAI-NORTH-STAR.md)",
standards/rules/â"Naming standard, visibility rules, test standards",
agents/â"Agent definition templates (.oct.md)",
templates/â"Project scaffolding templates",
library/skills/â"Ecosystem-wide operational skills",
library/agents/â"Agent definitions",
library/patterns/â"Reusable patterns and examples",
library/schemas/â"Schema definitions",
library/octave/â"OCTAVE usage guides",
tools/â"System utility scripts (validators, checkers)"
]
NOTE::"Agents CANNOT place artifacts in .hestai-sys/ â it is injected read-only at runtime"
PROJECT_GOVERNANCE[.hestai/]::[
north-star/â"North Star documents (000-*-NORTH-STAR.md + components/)",
decisions/â"Compiled governance decisions (debate outcomes, NOT ADRs)",
rules/â"Project standards, methodology, workflow guidance, specs",
schemas/â"Schema definitions"
]
DEVELOPER_DOCS[docs/]::[
adr/â"ADR-NNNN-topic.md (GitHub issue-based numbering per ADR-0031)",
api/â"API endpoint documentation",
development/â"Setup guides",
deployment/â"Deployment guides"
]
OPERATIONAL_STATE[.hestai/state/]::[
context/â"PROJECT-CONTEXT.md, PROJECT-CHECKLIST.md, PROJECT-HISTORY.md",
context/apps//â"APP-CONTEXT.md, APP-CHECKLIST.md, APP-HISTORY.md",
sessions/active/â"Active session working state",
sessions/archive/â"YYYY-MM-DD---octave.oct.md (committed) + raw.jsonl (gitignored)",
reports/â"YYYY-MM-DD-* audit reports, scan outputs, quality gate evidence"
]
DEBATE_ARTIFACTS[debates/]::[
jsonâGITIGNORED[full_debate_machine_format],
oct.mdâCOMMITTED[compressed_debate_synthesis]
]
CLAUDE_CODE[.claude/]::[
agents/â"Agent definitions (.oct.md)",
commands/â"Slash commands",
skills/â"Project-specific skills (per-repo, NOT ecosystem-wide)",
hooks/â"Git workflow automation"
]
NOTE::.claude/skills/âproject_specific|.hestai-sys/library/skills/âecosystem_wide
§3::PHASE_ARTIFACT_MAPPING
// Lifecycle: Spec (the plan) â Report (the evidence) â Doc (the product)
// Artifacts graduate through the lifecycle as phases progress
PLACEMENT::[
D1_NORTH_STAR::.hestai/north-star/[immutable_anchor],
D2_IDEAS_CONSTRAINTS_DESIGN::.hestai/rules/specs/[active_spec],
D3_BLUEPRINT::.hestai/rules/specs/[spec_MIGRATES_to_docs/_at_B1_gate],
B0_VALIDATION::.hestai/state/reports/[gate_evidence],
B1_BUILD_PLAN::.hestai/rules/specs/[task_breakdown_for_B2],
B2_IMPLEMENTATION_LOG::.hestai/state/reports/[evidence_stream],
B3_QA_SECURITY::.hestai/state/reports/[audit_trail],
B4_HANDOFF_USER_GUIDE::docs/[graduated_permanent_documentation]
]
GRADUATION_RULES::[
D3_blueprintâmigrates_from_.hestai/rules/specs/_to_docs/_at_B1_gate,
B0_architectural_decisionsârecorded_as_ADRs_in_docs/adr/,
B4_handoff_docsâgraduate_from_draft_to_docs/_at_delivery
]
ADR_SUPREMACY::[
RULE::"When in doubt between .hestai/decisions/ and docs/adr/ â choose docs/adr/",
.hestai/decisions/âcompiled_debate_decisions[agent_facing_OCTAVE_governance_outcomes],
docs/adr/âall_architecture_implementation_design_decisions[developer_facing_markdown],
DISTINCTION::"debate-hall exportsâ.hestai/decisions/[.oct.md] | developer decisionsâdocs/adr/[.md]"
]
// Per visibility-rules.oct.md FORMAT_RULES + FILE_RETENTION_POLICY
OCTAVE_FORMAT[.oct.md]::[
agent_definitions,
governance_rules,
north_star_summaries[agent_consumed],
methodology_docs,
context_files[PROJECT-CONTEXT_etc],
session_archives[compressed_semantic],
compiled_debate_decisions
]
MARKDOWN_FORMAT[.md]::[
north_star_full[human_authored_strategic_vision],
developer_guides[setup_deployment],
ADRs[architecture_decisions],
READMEs[navigation_pointers],
human_first_documentation
]
NOTE::"Full North Stars (.md) are human-authored vision; summaries (.oct.md) are agent-optimized"
FORMAT_DECISION_TREE::[
"Primary audience AI agents?"âYESâ.oct.md,
"Standards/methodology/system-standard?"âYESâ.oct.md,
"Primary audience human developers?"âYESâ.md,
"ADR or setup guide?"âYESâ.md
]
RETENTION_RULE::[
json_jsonl[raw]âGITIGNORED[machine_format+large+reconstructible],
oct.md[compressed]âCOMMITTED[semantic_density+audit_trail],
"Raw machine formats are ephemeral; semantic compressions are permanent"
]
§5::DOCUMENTATION_FIRST_PROTOCOL
SEQUENCE::[
1::write_docs_first[ADR+specification+blueprint],
2::merge_docs_PR[before_implementation],
3::implementation_PR_references_merged_docs[via_PR_number],
4::implementation_blocked_until_docs_merged
]
HANDOFF::"Docs PR merged (#N) â Implementation: 'Implements ADR-XXX (merged in PR #N)'"
MERGE_STRATEGY::[
D3_BLUEPRINT::immediate[before_B0],
ADRs::immediate[before_implementation],
API_DOCS::with_or_before_implementation,
ARCHITECTURE_AS_BUILT::with_implementation,
DEVIATIONS::as_discovered
]
CONTEXT_REQUIREMENTS::[
B1_01_B1_02::.hestai/rules/specs/[design_phase_artifacts],
MIGRATION_GATE::manual_checkpoint[verify_D3âdocs/],
B1_03_B1_05::docs/[implementation_documentation]
]
CRITICAL::"B1_02 in .hestai/rules/specs/, B1_03 in docs/ after manual migration"
// From visibility-rules.oct.md ANTI_PATTERNS
AVOID::[
DUPLICATE_CONTENT::"ADRs ONLY in docs/adr/ â never in .hestai/",
DEVELOPER_DOCS_IN_HESTAI::"Developers will not find setup guides in .hestai/ â use docs/",
COMMIT_EPHEMERAL::"Session handoffs go to .hestai/state/sessions/ (shared state, not git)",
MIX_ABSTRACTION_LEVELS::"Dashboard (PROJECT) guides to detail (APP) â no implementation in PROJECT-CONTEXT",
NON_NORTH_STAR_IN_NORTH_STAR_FOLDER::"Only 000--NORTH-STAR files and components/ belong in north-star/",
CONFUSE_DECISIONS_WITH_ADRS::".hestai/decisions/ = compiled governance decisions | docs/adr/ = formal ADRs",
PLACE_IN_HESTAI_SYS::".hestai-sys/ is read-only injected â agents cannot write there"
]
§8::PROJECT_CONTEXT_STATUS
PURPOSE::"Mitigate worktree isolation with visible project status"
LOCATION::.hestai/state/context/PROJECT-CONTEXT.md
SECTIONS::[
feature_name_and_branch,
blueprint_link::docs/,
ADR_status::[MERGED+IN_REVIEW],
current_phase::[B1+B2+B3+B4],
PR_link[with_WIP_marker],
agent_assigned
]
UPDATE_PROTOCOL::[
on_worktree_creation::update,
on_PR_merge::complete,
on_phase_gate::refresh
]
ARCHITECTURE_DOCS::[
applies_to_tag,
supersedes,
superseded_by,
schema_version,
phase::D3,
status::[ORIGINAL+AS_BUILT+DEVIATION]
]
ADR_DOCS::[
adr_number::"MUST match GitHub Issue number (zero-padded 4 digits)",
title,
status::[ACCEPTED+SUPERSEDED+DEPRECATED],
decision_date::ISO_8601,
implements::blueprint_section,
deviates_from
]
NUMBERING_RULE::"ADR-<GITHUB_ISSUE_NUMBER>-.md with zero-padded 4 digits"
LOCATION::docs/adr/
VALIDATION::scripts/ci/validate-doc-numbering.sh[enforced_on_push]
§10::CLEANUP_AT_PHASE_GATES
MANDATORY_POINTS::[
after_B1_02::before_migration,
after_B2_04::before_B3,
after_B3_04::before_B4,
after_B4_05::before_delivery
]
AGENT_BOUNDARIES::[
directory-curator::"Reports only",
workspace-architect::"Fixes violations, owns migrations",
holistic-orchestrator::"Enforces at gates"
]
TRIGGERS_WHEN::[documentation_created, artifact_placed, B1_migration]
CONSULT::[holistic-orchestrator, workspace-architect, system-steward]
COMPANION_DOCS::[
.hestai-sys/standards/rules/visibility-rules.oct.mdâ"WHERE does artifact belong?",
.hestai-sys/standards/rules/naming-standard.oct.mdâ"HOW to name once placed?",
.hestai/rules/hub-authoring-rules.oct.mdâ"WHERE in system governance payload?"
]
WISDOMS::[
"Documentation_is_prerequisite_not_side_effect",
"Timeline_determines_placement",
"B1_migration_is_critical_checkpoint",
"PROJECT-CONTEXT.md_prevents_worktree_blindness",
".hestai-sys/_is_read_only_system_governance"
]
More from this repository Supabase test harness patterns including local Supabase setup, test user creation via Auth Admin API, RLS testing, migration testing (db_reset), seed sequences, rate limiting, and environment detection. Use when setting up Supabase testing infrastructure, creating test users, troubleshooting Supabase test failures, or implementing RLS validation. Triggers on: supabase test setup, test user creation, supabase local testing, RLS testing, migration testing, supabase test harness, auth test helpers.
Supabase operational knowledge for migrations, RLS optimization, MCP tool benchmarks, and ADR-003 compliance. Use when validating database migrations, optimizing Row-Level Security policies, checking MCP tool performance, or ensuring Supabase operational standards. Triggers on: migration validation, RLS patterns, Supabase benchmarks, ADR-003, database state tracking, schema governance.
LLM-native structured communication format. Teaches OCTAVE syntax rules, canonical forms, and warning prevention for zero-error .oct.md authoring.
