| 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]"
]
§4::FORMAT_SELECTION
// 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
]
§6::B1_MIGRATION_GATE
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"
§7::ANTI_PATTERNS
// 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
]
§9::ADR_FRONT_MATTER
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"
]
§11::INTEGRATION
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"
]
===END===
