init_spec_knowledge

Instructions

Implementation Reference

• src/mk_spec_master/tools/spec_knowledge.py:109-131 (handler)

  The main handler function for the init_spec_knowledge tool. Takes arguments dict (project_name, overwrite), creates spec-knowledge.md from starter template. Idempotent - refuses to overwrite unless overwrite=True.

  def init_spec_knowledge_tool(arguments: dict) -> dict[str, Any]:
      """Create SPEC_PROJECT_ROOT/spec-knowledge.md from a starter template.
  
      Idempotent: refuses to clobber an existing file unless overwrite=True.
      """
      project_name = str(arguments.get("project_name") or config.PROJECT_ROOT.name)
      overwrite = bool(arguments.get("overwrite"))
  
      path = _knowledge_path()
      if path.exists() and not overwrite:
          return {
              "created": False,
              "path": str(path),
              "reason": "file already exists; pass overwrite=true to replace",
          }
  
      path.parent.mkdir(parents=True, exist_ok=True)
      path.write_text(_starter_content(project_name), encoding="utf-8")
      return {
          "created": True,
          "path": str(path),
          "bytes": path.stat().st_size,
      }

• src/mk_spec_master/server.py:384-390 (schema)

  Input schema for init_spec_knowledge: project_name (string, optional) and overwrite (boolean, default False) defined in the MCP Tool registration.

  inputSchema={
      "type": "object",
      "properties": {
          "project_name": {"type": "string"},
          "overwrite": {"type": "boolean", "default": False},
      },
  },

• src/mk_spec_master/server.py:373-391 (registration)

  MCP Tool registration for init_spec_knowledge with name, description, and inputSchema.

  Tool(
      name="init_spec_knowledge",
      description=(
          "Create SPEC_PROJECT_ROOT/spec-knowledge.md from a starter "
          "template. The file carries spec methodology (EARS, INVEST, "
          "AC quality rules) plus TODO sections for the team's domain "
          "rules / actors / glossary. Other mk-spec-master tools "
          "lean on this indirectly via get_spec_context. Idempotent "
          "— refuses to overwrite an existing file unless "
          "overwrite=true. Optional project_name labels the file."
      ),
      inputSchema={
          "type": "object",
          "properties": {
              "project_name": {"type": "string"},
              "overwrite": {"type": "boolean", "default": False},
          },
      },
  ),

• src/mk_spec_master/server.py:58-58 (registration)

  Maps the string 'init_spec_knowledge' to the spec_knowledge_tools.init_spec_knowledge_tool handler function in the tool registry.

  "init_spec_knowledge": spec_knowledge_tools.init_spec_knowledge_tool,

• src/mk_spec_master/tools/spec_knowledge.py:91-106 (helper)

  Helper functions: _knowledge_path() returns the path to spec-knowledge.md, _starter_content(project_name) builds the full starter markdown content combining universal methodology and domain TODO sections.

  def _knowledge_path():
      return config.PROJECT_ROOT / "spec-knowledge.md"
  
  
  def _starter_content(project_name: str) -> str:
      return (
          f"# Spec knowledge — {project_name}\n\n"
          "> Methodology + domain glossary that mk-spec-master tools "
          "(`analyze_spec_quality`, `propose_spec_improvements`, "
          "`get_optimization_plan`) lean on indirectly. The AI client should "
          "call `get_spec_context` near the start of each session so the same "
          "rules colour every spec interpretation that follows.\n\n"
          + _UNIVERSAL_METHODOLOGY
          + "\n"
          + _DOMAIN_TODO_SECTIONS
      )