nalbam · Oct 3, 2026 · Oct 3, 2026 · Oct 3, 2026 · Oct 3, 2026 · Oct 3, 2026
@@ -6,6 +6,21 @@ capabilities. Skills are reusable across environments; bundled MCP endpoints
 include the supported `argocd-env-demo` deployment profile.
 Everything is [MIT-licensed](LICENSE).
 
+## Start here
+
+| Your task | Read |
+|---|---|
+| Configure an Agent and connect tools | [Host app integration](docs/agent-studio.md) |
+| Run coding and file tasks | [Workspace agent profile](docs/code-agent.md) |
+| Process recordings | [Audio agent profile](docs/audio-agent.md) |
+| Write or update documentation | [Documentation writing guidelines](#documentation-writing-guidelines) |
+| Add or change a skill | [Writing and maintaining skills](#writing-and-maintaining-skills) |
+| Check a repository change | [Validation commands](#validation) |
+
+MCP (Model Context Protocol) connects the host app to external tools and data.
+Installing a plugin registers its content; the Agent still needs tool bindings
+and any required account connection.
+
 ## Scope and runtime
 
 Reusable task guidance and provider-specific integrations have separate scopes.
@@ -108,6 +123,40 @@ AWS Knowledge supplies AWS documentation, not general research or live account
 state. Use the sources relevant to the actual question. Plaud, Notion and GitHub
 operate under the connected identity and discovered schemas.
 
+## Documentation writing guidelines
+
+Write so readers can **find, understand and use** the information, following
+ISO 24495-1. Write **short, clear and unambiguous** text, following the approach
+of ASD-STE100.
+
+Apply these principles to the README, operator guides, prompts, skills, references
+and templates:
+
+- Start with the reader's task and the result they need. Keep relevant facts,
+  prerequisites and limits; remove repetition.
+- Use descriptive headings and links. Put steps in execution order and keep
+  conditions beside the action they control.
+- Use one term for one concept. Explain unfamiliar terms on first use, and retain
+  exact API names, identifiers, commands and quoted text.
+- State who does what and when. Give each instruction one main action; split long
+  sentences without dropping conditions, uncertainty or causal relationships.
+- Give the inputs, expected result and verification needed to act. Distinguish
+  required steps, defaults, examples and optional actions.
+
+Before delivery, follow a representative task using only the document. Check that
+the reader can locate the starting point, interpret the conditions and verify the
+result. Check links, commands and examples against their source contracts. Record
+unverified steps; a static check does not establish reader usability.
+
+These are writing principles, not a claim of certification or full standards
+conformance. ASD-STE100 controls English vocabulary and grammar; do not impose its
+English word lists or word-count rules on Korean text. Preserve the user's
+language, required format and technical meaning.
+
+Sources: [ISO 24495-1:2023](https://www.iso.org/standard/78907.html),
+[the four plain-language principles](https://www.iplfederation.org/iso-standard/),
+and [ASD-STE100](https://www.asd-ste100.org/about_STE.html).
+
 ## Writing and maintaining skills
 
 Use [skill-writer](plugins/agent-craft/skills/skill-writer/SKILL.md) for selection

@@ -27,6 +27,8 @@ retrieval is not supplied by this repository; when transcript access is absent,
 request transcript text or use available sources and identify the evidence limit.
 Video metadata alone does not establish what was spoken.
 
+### Agent Memory
+
 Agent Memory separates durable Memory from document chunks and graph context.
 `recall` returns compact Memory text with IDs and versions; `context_search`
 searches across those source types and supplies detailed evidence. `remember`
@@ -42,6 +44,8 @@ not enable it. Search result IDs belong to Agent Memory, not the host app's arti
 Use the [connection notes](integrations/agent-memory.md) for current console text
 and installation-side verification; the server is registered independently of Plugin sync.
 
+### Endpoint ownership
+
 `mcp.json` contains provider-hosted and declared in-cluster deployment addresses.
 Other organization URLs, credentials, model selections and Agent bindings
 belong to the installing side. Adding a similarly named service to the manifest
@@ -146,6 +150,8 @@ entries for the request. This supplements explicit bindings; it does not make
 every installed skill or tool available. Use the actual offered list and schemas.
 OAuth-backed MCP discovery still requires that Agent's connection.
 
+### Files and artifacts
+
 The host app extracts attachments and, when artifact storage succeeds, retains
 originals with file IDs. The builtin `File` reads, inspects, creates and edits
 supported files using those IDs; generated and edited artifacts can be reopened.
@@ -159,6 +165,8 @@ Plain text, Markdown, CSV, JSON, HTML and SVG creation uses `SaveFile` (UTF-8
 HTML inspection returns source while reading extracts safe text. `SaveFile` and
 `File` create/edit share ten write attempts per run, including failed attempts.
 
+### MCP results visible to the model
+
 For MCP results with non-empty `content`, the model receives those blocks, not
 the accompanying `structuredContent`. Check visible counts and validation
 messages; absent metadata is not proof that an extraction is complete. Server
@@ -211,6 +219,8 @@ The operator connects the Sandbox backend and Workspace worker. The `Workspace`
 of an enabled Agent; bind workspace-task and sandbox-task in its current settings.
 The actual tool schemas remain authoritative.
 
+### Start and observe a task
+
 `options` reads available runtimes, default_runtime and registered repositories. There is no default repository. `start` queues a
 new Workspace; `run` continues a returned workspace_id. For work without Git,
 repository and base_branch are null. `status` and bounded `wait` return output,
@@ -221,6 +231,8 @@ When the offered `start` schema includes `title`, use a short purpose label in t
 user's language. It labels the Workspace and its Chat; the script or coding task
 stays in `task`. Do not copy a command script into the title or send an unsupported field.
 
+### Git publication
+
 A coding request includes commit, work-branch push and pull-request publication through
 prepare_git without another approval, unless the user limits the scope. Main merge,
 direct main push, tags, releases and configured workflow dispatch require a separate
@@ -229,6 +241,8 @@ releases bind to an existing tag and its exact commit. General agent
 descriptions and system prompts identify capabilities; account, repository,
 branch and requested file changes belong in each user's task input.
 
+### Reuse and close a Workspace
+
 Read options.current_workspace before creating compute. Repeated start returns the
 selection without queueing another task; run continues it. close keeps files and
 selection, and run/prepare_git can restore a closed Workspace. attach_repository

@@ -4,7 +4,7 @@ Plaud 녹음의 원본 보관·전사·요약을 하나의 Agent와 AudioJob wor
 [시스템 프롬프트](prompts/audio-agent.md)를 사용하고 `audio-processing`을 명시적으로 연결한다.
 회의록 양식이 필요하면 `meeting-minutes`, 문장 편집이 필요하면 `korean-humanize`를 추가한다.
 
-설치에서 확인할 조건:
+## 설치 조건
 
 - Agent의 오디오 처리 도구, Plaud MCP 연결과 `get_file`의 source_ref 매핑.
 - Models에 등록된 **transcription** 모델과 실제로 접근 가능한 provider endpoint·credential.
@@ -13,6 +13,8 @@ Plaud 녹음의 원본 보관·전사·요약을 하나의 Agent와 AudioJob wor
   후처리는 같은 Agent의 현재 설정을 사용하며 versionName을 전달하지 않는다.
 - 비공개 파일 저장소와 audio-worker. EKS의 S3·Pod Identity와 k3s의 MinIO 연결은 각 설치 설정이다.
 
+## 처리 결과 확인
+
 먼저 config와 Plaud 읽기 도구를 확인한 뒤, 사용자가 지정한 녹음 한 건으로 원본·전사·요약
 Artifact의 실제 내용을 확인한다. 같은 요청을 반복했을 때 기존 job과 결과를 재사용하는지도 확인한다.
 계정 연결은 테스트·운영에서 각각 확인하며 OAuth token을 다른 설치로 복사하지 않는다.

@@ -2,17 +2,25 @@
 
 호스트 앱의 Agent 이름과 관계없이 적용하는 공용 프로필이다. Agent는 요청을 조율하고,
 Workspace의 코딩 Runtime 또는 command가 파일 작업을 실행한다. Sandbox는 별도 MCP 서버가 아니다.
-Agent 현재 설정에서 워크스페이스 도구를 활성화한다. 모델은 Models에서 Runtime별로 선택하고
-Agent의 워크스페이스 도구 탭에서 소유자·관리자가 저장소와 기본 Runtime을 관리한다.
-기본 저장소는 없으며 접근 모드 기본은 등록 + 신규다. 계정·Worker·이미지는 설치 측 설정이다.
-저장소 고정·소유자 지정·모든 저장소·신규 자동 허용을 지원한다. 신규 모드는 Workspace 도구가
-실제로 생성한 저장소를 자동 등록하며, 기존 저장소는 소유자·관리자가 명시적으로 등록한다.
+
+## 실행 환경 설정
+
+1. Agent 현재 설정에서 워크스페이스 도구를 활성화한다.
+2. Models에서 Runtime별 모델을 선택한다.
+3. 소유자·관리자가 Agent의 워크스페이스 도구 탭에서 저장소 정책과 기본 Runtime을 설정한다.
+4. 설치 측에서 계정·Worker·이미지를 설정한다.
+
+기본 저장소는 없으며 접근 모드 기본은 등록 + 신규다. 지원하는 정책은 저장소 고정,
+소유자 지정, 모든 저장소, 신규 자동 허용이다. 신규 모드는 Workspace 도구가 실제로 생성한
+저장소를 자동 등록한다. 기존 저장소는 소유자·관리자가 명시적으로 등록한다.
 
 ## 설명과 시스템 프롬프트
 
 설명 예시:
 
-> Workspace와 Sandbox에서 코드·파일·데이터 작업을 수행하는 공용 에이전트. PR 리뷰, Issue 수정, 기능 구현, 리팩토링, 의존성 업그레이드, CI 실패 조사, 보안 수정과 프로젝트 생성을 지원하고 실제 검증과 작업 브랜치 PR까지 제공하고, 요청한 병합·태그·릴리즈·배포를 조율한다.
+> Workspace와 Sandbox에서 코드·파일·데이터 작업을 수행하는 공용 에이전트다.
+> PR 리뷰, Issue 수정, 기능 구현, 리팩토링, 의존성 업그레이드, CI 실패 조사, 보안 수정과 프로젝트 생성을 지원한다.
+> 구현·수정 작업은 검증과 작업 브랜치 PR까지 제공한다. 병합·태그·릴리즈·배포는 요청된 범위에서 조율한다.
 
 시스템 프롬프트는 [workspace-agent.md](prompts/workspace-agent.md)를 그대로 사용한다.
 코딩 요청의 기본 완료 범위는 새 작업 브랜치의 구현·검증·커밋·푸시·PR이다.

@@ -1,19 +1,27 @@
 # PR 자동 리뷰 Agent
 
+## Agent와 저장소 선택
+
 [code-review-agent.md](prompts/code-review-agent.md) 프롬프트와 `code-review` Skill을 연결한다.
 Agent의 Webhook 동작에서 GitHub PR 리뷰를 선택하고 설치의 GitHub 계정이 접근 가능한
 저장소 전체 또는 명시적 `owner/repo` 목록을 설정한다. 공유 GitHub 연결로 댓글을 쓰는
 설정이므로 관리자가 활성화한다. 기본 Agent 공개 범위는 검토 자료의 접근 범위에 맞춘다.
 
+## GitHub Webhook 연결
+
 GitHub 저장소에서 Payload URL을 `/api/webhook/{agent}`로, Content type을
 `application/json`으로 지정하고 해당 Agent Webhook Secret과 Pull requests 이벤트를
 등록한다. 시크릿은 저장소 파일·Agent 프롬프트·PR·로그에 넣지 않는다.
 저장소를 읽을 수 있어도 Pull requests 쓰기 권한이 없으면 댓글 게시가 실패한다.
 
+## Workspace 실행 설정
+
 Agent의 Workspace 도구와 command 런타임, 대상 저장소 정책, Sandbox와 worker를 설정하고
 Webhook의 `내 권한으로 실행`을 소유자가 명시적으로 켠다. 공유 GitHub 리뷰 권한과
 Workspace 실행 위임은 별도 설정이다. webhook actor의 동시 실행 한도는 2 이상이어야 한다.
 
+## 리뷰 실행과 게시
+
 호스트 앱이 서명·저장소·PR·HEAD를 검증하고 Workspace를 만든 뒤 서버 Git bundle로 정확한
 HEAD를 받는다. Agent는 Skill·ReviewSource와 준비된 Workspace에서 관련 코드와 테스트를
 읽고 필요한 격리 검사를 실행한다. 검사의 실제 완료 결과를 읽고 최종 리뷰 본문을 작성한다.
@@ -22,6 +30,8 @@ HEAD를 받는다. Agent는 Skill·ReviewSource와 준비된 Workspace에서 관
 소스 수정·Git publication·PR 승인·merge·배포를 실행하지 않는다.
 최대 파일 수·diff 문맥 한도와 누락 여부는 실제 실행 입력과 게시 본문에 표시된다.
 
+## 이벤트와 결과 확인
+
 `opened`, `synchronize`, `reopened`, `ready_for_review`가 열린 일반 PR의 리뷰를 요청한다.
 같은 HEAD는 중복 처리하지 않으며 실행 중 HEAD가 바뀌면 오래된 리뷰를 게시하지 않는다.
 GitHub ping은 연결 검사일 뿐 리뷰 성공이 아니다. Trigger 전달 이력의 `review.status`와

@@ -20,11 +20,40 @@ Neither the description nor the notes configure account access or permissions.
 ```markdown
 # Agent Memory 연결
 
-- 접근 범위: X-User-Email 없는 조직 Agent token은 조직 범위에 한정됩니다. 검증된 활성 멤버의 X-User-Email을 전달하면 해당 멤버의 권한을 적용합니다. Studio가 이 예약 헤더를 구성하므로 Agent 설정에서 신원을 임의로 덮어쓰지 않습니다. X-Tenant-Id와 X-Conversation-Id는 접근 권한을 부여하지 않습니다.
-- 도구: recall은 장기 Memory를 회상하고 context_search는 Memory·문서·지식 그래프를 함께 검색합니다. remember는 지정 scope에 Memory를 저장하며 forget은 manage 권한과 현재 version으로 archive합니다. document_ingest는 텍스트 문서 처리를 접수하며 document_ingest_status가 ready인지 확인해야 검색 가능한 문서로 안내할 수 있습니다. 실제 도구 목록과 schema가 기준입니다.
-- 연결 확인: Test connection은 도구 목록 조회만 검증합니다. 사용할 Agent의 현재 설정에 서버를 연결하고 필요한 도구를 허용한 뒤 대표 요청을 실제 실행합니다.
-- 자동 회상: Agent 현재 설정의 memoryRecall을 켜고 recall을 명시적으로 바인딩합니다. 차단되거나 승인이 필요한 recall은 사전 회상에서 제외됩니다. 동적 검색으로 찾은 서버는 사전 회상 대상이 아닙니다.
-- 인증값 교체: 서버의 token을 재생성한 경우 등록된 Authorization 헤더와 Agent별 헤더 오버라이드를 필요한 범위에서 갱신합니다. 인증값을 메모·예시·응답에 적지 않습니다.
+## 접근 범위
+
+X-User-Email 없는 조직 Agent token은 조직 범위에 한정됩니다.
+검증된 활성 멤버의 X-User-Email을 전달하면 해당 멤버의 권한을 적용합니다.
+Studio가 이 예약 헤더를 구성하므로 Agent 설정에서 신원을 임의로 덮어쓰지 않습니다.
+X-Tenant-Id와 X-Conversation-Id는 접근 권한을 부여하지 않습니다.
+
+## 도구와 완료 상태
+
+| 도구 | 역할과 확인 조건 |
+|---|---|
+| recall | 장기 Memory 회상 |
+| context_search | Memory·문서·지식 그래프 검색 |
+| remember | 지정 scope에 Memory 저장 |
+| forget | manage 권한과 현재 version으로 보관 처리(archive) |
+| document_ingest | 텍스트 문서 처리 접수 |
+| document_ingest_status | ready이면 검색 가능한 문서로 안내 |
+
+실제 도구 목록과 schema가 기준입니다.
+
+## 연결과 자동 회상
+
+1. Test connection으로 도구 목록 조회를 확인합니다.
+2. 사용할 Agent의 현재 설정에 서버를 연결하고 필요한 도구를 허용합니다.
+3. 대표 요청을 실제 실행해 접근 범위를 확인합니다.
+4. 자동 회상이 필요하면 memoryRecall을 켜고 recall을 명시적으로 바인딩합니다.
+
+차단되거나 승인이 필요한 recall은 사전 회상에서 제외됩니다.
+동적 검색으로 찾은 서버는 사전 회상 대상이 아닙니다.
+
+## 인증값 교체
+
+서버의 token을 재생성했으면 등록된 Authorization 헤더와 Agent별 헤더 오버라이드를
+필요한 범위에서 갱신합니다. 인증값을 메모·예시·응답에 적지 않습니다.
 
 이 본문은 운영자 메모이며 모델에 전달되지 않습니다. 저장·변경 권한과 응답 규칙은 Agent의 시스템 프롬프트 또는 연결 Skill에 둡니다.
 ```